SugarCRM SupportDocumentationSugar DeveloperSugar Developer Guide 9.0IntroductionMigration Guide

Migration Guide

Overview

The purpose of this document is to provide insight to Sugar Developers for upgrading custom Sugar code, extensions, and integrations to Sugar 9.0 and Spring '19 releases. This guide focuses on changes in Sugar 9.0 that could cause an immediate impact on Sugar customizations and integrations built for Sugar 8.3 (Winter '19) or Sugar 8.0.

Intended Sugar Upgrade Path

The following upgrade paths are supported for this release:

Please refer to the appropriate section of this page for your intended migration scenario.

For the majority of customers hosted on SugarCloud, upgrades are scheduled automatically. For on-site customers, please plan on upgrading before the end of October 2019, which is the end of standard support. Please refer to Supported Versions: End-of-Life Plan for more details.

Migrating From Winter '19 (8.3)

Expected to Affect Most Developers

This section explains items expected to have the widest impact on Sugar customizations and integrations when migrated to Sugar Spring '19 (9.0). We expect that these items will affect most developers.

Advanced Workflow is now called SugarBPM™

While not having any direct functional impact on Sugar customizations, the references in Sugar and in Sugar documentation to "Advanced Workflow" will be changed to "SugarBPM™". We request that you update any documentation or collateral associated with this Sugar Enterprise feature to coincide with Sugar 9.0 release.

New Sugar REST API endpoints

The following two new REST API endpoints have been added in this Sugar release.

  • GET /rest/<Opportunities | Quotes>/recent-product
  • GET /rest/<Opportunities | Quotes>/favorites

The HTTP POST versions of these endpoints are deprecated and will be removed in a future major Sugar REST API version. The HTTP GET endpoints are preferred since these operations does not modify any data and can be cached (ex. using HTTP caching).

PHP 7.3 Support

This Sugar release introduces PHP 7.3 support. At the time of this writing, SugarCloud continues to use PHP 7.1, but on-site customers can start taking advantage of PHP 7.3 after upgrading to Sugar 9.0. At this time, some DB vendors and PHP extension authors have not yet updated their libraries to support PHP 7.3. For example, DB2 support is still pending.

For more information about PHP 7.3 support, check out the recent blog Preparing for PHP 7.3 support.

Expected to Affect Few Developers

This section explains items expected to have a low impact on Sugar customizations and integrations when migrated to Sugar Spring '19 (9.0). It is expected that these items will affect few developers.

Deprecated Analytics and Feedback components

We've deprecated Sugar's support for Google Analytics. The following JavaScript class and associated functions have been deprecated and will be removed in a future Sugar release.

  • SUGAR.analytics.connectors.GoogleAnalytics
  • SUGAR.analytics.connectors.GoogleAnalytics.initialize()
  • SUGAR.analytics.connectors.GoogleAnalytics.start()
  • SUGAR.analytics.connectors.GoogleAnalytics.trackPageView()
  • SUGAR.analytics.connectors.GoogleAnalytics.trackEvent()
  • SUGAR.analytics.connectors.GoogleAnalytics.set()
  • SUGAR.analytics.connectors.GoogleAnalytics.enableIPAnonymization()

We have also deprecated the existing Sugar Feedback module which will be removed in a future Sugar release. This module only contained the following Sidecar components.

Name File Path
FeedbacksRatingField ./modules/Feedbacks/clients/base/fields/rating/
FeedbacksFeedbackView ./modules/Feedbacks/clients/base/views/feedback/

Migrating From Spring '18 (8.0)

Sugar 9.0 is an on-site release. For on-site customers upgrading from Sugar Spring '18 (8.0), this release contains all the features delivered in our Summer '18, Fall '18, and Winter '19 releases. The following is a summary of the migration steps necessary to get to Spring '19.

Expected to Affect Most Developers

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

Advanced Workflow is now called SugarBPM™

While not having any direct functional impact on Sugar customizations, the references in Sugar and in Sugar documentation to "Advanced Workflow" will be changed to "SugarBPM™". We request that you update any documentation or collateral associated with this Sugar Enterprise feature to coincide with Sugar 9.0 release.

New Sugar REST API endpoints

The following two new REST API endpoints have been added in this Sugar release.

  • GET /rest/<Opportunities | Quotes>/recent-product
  • GET /rest/<Opportunities | Quotes>/favorites

The HTTP POST versions of these endpoints are deprecated and will be removed in a future major Sugar REST API version. The HTTP GET endpoints are preferred since these operations does not modify any data and can be cached (ex. using HTTP caching).

PHP 7.3 Support

This Sugar release introduces PHP 7.3 support. At the time of this writing, SugarCloud continues to use PHP 7.1, but on-site customers can start taking advantage of PHP 7.3 after upgrading to Sugar 9.0. At this time, some DB vendors and PHP extension authors have not yet updated their libraries to support PHP 7.3. For example, DB2 support is still pending.

For more information about PHP 7.3 support, check out the recent blog Preparing for PHP 7.3 support.

Sidecar JavaScript library updates

The following Sidecar JS libraries have been upgraded in this Sugar release.

jQuery Migrate should help maintain compatibility for custom BWC code using older jQuery APIs. Custom code that uses deprecated jQuery APIs should be updated as soon as possible.

As part of the jQuery upgrade, the following jQuery plug-ins needed to be updated to be compatible with v3.3.1.

  • ./include/javascript/jquery/markitup: v1.1 → v1.1.15 (changelog)
  • ./include/javascript/pmse/lib/jquery.layout-latest.js: v1.3.0 → v1.6.3 (changelog)
  • ./include/javascript/jquery/jquery.timepicker.js: 1.8.8 → 1.11.14 (changelog)
  • ./include/javascript/jquery/bootstrap/bootstrap.min.js (v2.0.0) is removed and replaced by include/javascript/twitterbootstrap/bootstrap.min.js (v2.2.1) (changelog)

Introduction of REST API v11.4

This Sugar release introduces the v11.4 REST API version. The following new REST APIs have been added in v11.4. 

Lean Count endpoints for Subpanels

The following API endpoints provide an efficient way to return the count of related records. These new API endpoints are used when displaying our Record subpanels. This should improve responsiveness of Sugar record views with many related records.

  • GET rest/<module>/<id>/link/<link_name>/leancount
  • GET rest/<module>/<id>/link/<link_name>/filter/leancount

Comments Log endpoints

As part of new Comments Log field, Sugar now includes Worklog module that supports only the following REST API endpoint. 

  • GET rest/Worklog/<GUID>

POST, PUT, and DELETE are not supported on this module.

PDF Manager endpoint

With the addition of the following PdfManager endpoint, it is now possible to retrieve generated PDFs (such as Quotes, Invoices, etc.) using the REST API.

  • GET /rest/PdfManager/generate

Product Catalog Quick Picks endpoint

The following endpoints are used by the new Product Catalog Quick Picks dashlet to retrieve favorite and recently used products.

  • POST /rest/<Opportunities | Quotes>/recent-product
  • POST /rest/<Opportunities | Quotes>/favorites

PHP library and code changes to prepare for PHP 7.3 support in Sugar 9.0

Some code changes were made to ensure compatibility with 7.3.

In this Sugar release, the following PHP libraries were updated.

  • doctrine/dbal: 2.7.1 → 2.8.0 (changelog)
  • ramsey/uuid: 2.9.0 → 3.8.0 (changelog)
  • symfony/{cache,console,framework-bundle,security-core,security-csrf,translation,validator}: 3.4.8 → 3.4.16 (changelog)
  • tedivm/jshrink: 1.1.0 → 1.3.1 (changelog)
  • onelogin/php-saml: v2.11 → v3.0 (changelog)

Additionally, we made some minor changes to the following vendor libraries for PHP 7.3 compatibility:

  • Smarty
  • XTemplate
  • HTMLPurifier

If you have custom code that uses any of the above libraries, you should verify that your customizations are still compatible.

Finally, here are some other things to look out for in your customizations today so you can be ready for PHP 7.3.

Default Dashboard metadata is no longer supported

Sugar's out of the box default dashboard metadata files have been removed in this Sugar release. These files specified the default List view and Record view dashboards used by our out of the box modules. This default information is now stored in the Dashboards module in the Sugar database. There should be no impact on existing customizations unless they include one of the removed PHP files. 

The following files have been removed in this Sugar release. 

  • ./modules/<module>/clients/base/layouts/record-dashboard/record-dashboard.php 
  • ./modules/<module>/clients/base/layouts/list-dashboard/list-dashboard.php

Custom Sugar dashboards should no longer be defined via metadata. Customizations should use Default Dashboards feature instead of defining dashboard metadata. During upgrade to Sugar Winter '19, any pre-existing custom metadata dashboards will be migrated into a default dashboard record that is shared globally and assigned to Admin user.

Module Loadable Packages that install custom dashboards will need to be updated to remove the custom dashboard metadata since it will no longer be supported.

Expected to Affect Few Developers

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

Removal of JIT Chart library

The deprecated JIT chart library has been removed in this Sugar release. The JIT chart library was deprecated in Sugar 7.10 and has been replaced by Sucrose charts. Please ensure you have removed any code that uses JIT charts prior to upgrading.

Deprecated jQuery Plugins

The following jQuery plugins are deprecated and will be removed in a future Sugar release. They are currently unused by core Sugar application. Please verify that JavaScript code customizations do not rely on these deprecated libraries. 

  • ./include/javascript/jquery/jquery.dataTables.customSort.js 
  • ./include/javascript/jquery/jquery.dataTables.min.js 
  • ./include/javascript/jquery/jquery.droparea.js 
  • ./include/javascript/jquery/jquery.elementReady.js 
  • ./include/javascript/jquery/jquery.highLight.js 
  • ./include/javascript/jquery/jquery.hotkeys.js 
  • ./include/javascript/jquery/jquery.hoverIntent.js 
  • ./include/javascript/jquery/jquery.hoverscroll.js 
  • ./include/javascript/jquery/jquery.popoverext.js 
  • ./include/javascript/jquery/jquery.watch.js

Updated BWC / SugarMVC jQuery libraries

The following BWC (SugarMVC) JavaScript libraries have been upgraded in this Sugar release. 

jQuery Migrate should help maintain compatibility for custom BWC code using older jQuery APIs. Custom code that uses deprecated jQuery APIs should be updated as soon as possible.

REST API Version Increase

This Sugar release introduces REST API version 11.3. This new REST API version introduces some new features described further below.

New Quotes Configuration interface for Administrators

Sugar Administrators can now configure the Summary Bar Header, Worksheet Columns, and Grand Totals Footer used by the Quotes module. This makes it much easier to perform many common changes that would have previously needed code customizations.

Please test to ensure that your Quotes customizations are compatible with configuration changes created using the Quotes configuration interface.

New REST API endpoints

  • GET /rest/Quotes/config
  • POST /rest/Quotes/config

New Sidecar Views

View File Path
QuotesConfigColumnsView ./modules/Quotes/clients/base/views/config-columns/
QuotesConfigFooterView ./modules/Quotes/clients/base/views/config-footer/
QuotesConfigTotalsFooterRowsView ./modules/Quotes/clients/base/views/config-totals-footer-rows/
QuotesConfigSummaryView ./modules/Quotes/clients/base/views/config-summary/
QuotesConfigDrawerHowtoView ./modules/Quotes/clients/base/views/config-drawer-howto/
QuotesConfigHeaderButtonsView ./modules/Quotes/clients/base/views/config-header-buttons/
QuotesConfigListHeaderColumnsView ./modules/Quotes/clients/base/views/config-list-header-columns/
QuotesConfigPanelView ./modules/Quotes/clients/base/views/config-panel/

New Sidecar Layouts

View File Path
QuotesConfigDrawerContentLayout ./modules/Quotes/clients/base/layouts/config-drawer-content/
QuotesConfigDrawerLayout ./modules/Quotes/clients/base/layouts/config-drawer/

New Sidecar Field

View File Path
QuotesTristateCheckboxField ./modules/Quotes/clients/base/fields/tristate-checkbox/

JavaScript Library Upgrades

In this release, we've upgraded Handlebars, Underscore, jQuery, jQuery UI, jQuery Migrate to newer versions.

  • Handlebars has been upgraded from 1.3.0 to 1.3.1-sugarcrm-temporary to include fixes from newer versions. (release notes)
  • Underscore has be upgraded from 1.8.3 to 1.9.1. (changelog)
  • jQuery has been upgraded from 1.11.3 to 1.12.4.  (changelog)
  • jQuery Migrate has been upgraded from 1.2.1 to 1.4.1. (changelogs: 1.3.0 and 1.4.1)
  • jQuery UI has been upgraded from 1.11.4 to 1.12.1. (changelogs: 1.12.0 and 1.12.1)

See You'll never guess which libraries are changing in the upcoming Sugar release for more details on how we expect these upgrades to affect your integrations and customizations.

Removal of Old Identity Management Code

As part of implementing a new Identity Manager, the following files relating to LDAP were removed:

  • ./modules/Users/authentication/EmailAuthenticate/EmailAuthenticate.php
  • ./modules/Users/authentication/EmailAuthenticate/EmailAuthenticateUser.php
  • ./modules/Users/authentication/LDAPAuthenticate/LDAPAuthenticate.php
  • ./modules/Users/authentication/LDAPAuthenticate/LDAPAuthenticateUser.php
  • ./modules/Users/authentication/LDAPAuthenticate/LDAPConfigs/default.php
  • ./modules/Users/authentication/SAMLAuthenticate/SAMLAuthenticate.php
  • ./modules/Users/authentication/SAMLAuthenticate/SAMLAuthenticateUser.php
  • ./modules/Users/authentication/SAMLAuthenticate/SAMLRequestRegistry.php
  • ./modules/Users/authentication/SAMLAuthenticate/index.php
  • ./modules/Users/authentication/SAMLAuthenticate/saml.php
  • ./modules/Users/authentication/SAMLAuthenticate/settings.php
  • ./modules/Users/authentication/SugarAuthenticate/SugarAuthenticate.php
  • ./modules/Users/authentication/SugarAuthenticate/SugarAuthenticateExternal.php
  • ./modules/Users/authentication/SugarAuthenticate/SugarAuthenticateUser.php

The following classes were replaced:

  • SAMLAuthenticate was replaced with IdMSAMLAuthenticate
  • LDAPAuthenticate was replaced with IdMLDAPAuthenticate
  • SugarAuthenticate was replaced with IdMSugarAuthenticate
  • SugarAuthenticateExternal was replaced with ExternalLoginInterface

If you have customized authentication, you should test to ensure it is still working correctly. If you relied on any of the removed files then you will need to reimplement your customizations.

Updated Character Set and Collation for MySQL Databases

In order to support importing and displaying emails that contain emoji, MySQL databases now use the character set utf8mb4 and collation utf8mb4_general_ci.  The character set and collation will be set automatically for new instances of Sugar and updated during the upgrade of existing instances of Sugar.  

If you have changed the default DB collation and you are using a MySQL database, then you should ensure that your collation is utf8mb4-compatible prior to the upgrade. The collation can be set by the admin in Admin > Locale > Collation or by modifying ./config_override.php. If your collation is utf8mb4-compatible, the upgrade will automatically migrate the collation to utf8mb4. For example, if you have set your collation to be utf8_swedish_ci, the upgrade will migrate the collation to utf8mb4_swedish_ci. If no collation is set, Sugar's cloud service will use the default utf8mb4_general_ci.

Tables with very large row sizes (for example, custom tables with a large number of custom fields) may be unable to be automatically upgraded. The upgrade script will notify you if a table would exceed the single-row size supported by MySQL (65,535 bytes) upon conversion to utf8mb4. In order to reduce the row size, we recommend the following:

  • Remove any/all fields that are not being used.
  • Reduce the lengths for char/varchar fields (e.g. size of longest existing value plus some padding).
  • Replace large varchar fields with text fields. Text fields are roughly 10 bytes, so significant size reduction exists when text fields can replace large varchar fields (e.g. VARCHAR(255)).

We do not anticipate issues for instances that are upgraded, but we do recommend doing upgrade testing.

Microsoft Windows Stack Improvements

The Sugar 9.0 on-site release adds support for Windows Server 2016, IIS 10, and SQL Server 2017 while dropping support for older Microsoft software versions. Check out the Sugar 9.0 Supported Platforms documentation for full platform details.

When planning a 9.0 upgrade of an existing Sugar instance using SQL Server, we recommend upgrading Sugar to 9.0 before upgrading to Windows Server 2016 and to SQL Server 2017.

We also addressed a long standing issue that could cause list view performance issues with large data sets on SQL Server. We have converted Sugar module ID fields used with Microsoft SQL Server from varchar to nvarchar data type. For existing Sugar installations, this conversion will happen during upgrade.

Deprecated Analytics and Feedback components

We've deprecated Sugar's support for Google Analytics. The following JavaScript class and associated functions have been deprecated and will be removed in a future Sugar release.

  • SUGAR.analytics.connectors.GoogleAnalytics
  • SUGAR.analytics.connectors.GoogleAnalytics.initialize()
  • SUGAR.analytics.connectors.GoogleAnalytics.start()
  • SUGAR.analytics.connectors.GoogleAnalytics.trackPageView()
  • SUGAR.analytics.connectors.GoogleAnalytics.trackEvent()
  • SUGAR.analytics.connectors.GoogleAnalytics.set()
  • SUGAR.analytics.connectors.GoogleAnalytics.enableIPAnonymization()

We have also deprecated the existing Sugar Feedback module which will be removed in a future Sugar release. This module only contained the following Sidecar components.

Name File Path
FeedbacksRatingField ./modules/Feedbacks/clients/base/fields/rating/
FeedbacksFeedbackView ./modules/Feedbacks/clients/base/views/feedback/

Expected to Affect Some Developers

This section explains items expected to have a moderate impact on Sugar customizations and integrations when migrated to Sugar Spring '19 (9.0). It is expected that these items will affect some developers.

Changes to the Login Page

The Sugar login page has been updated to display content from SugarCRM. The content will not display on any window smaller than 1024px, which means that the content will not display on most phones and tablets. We recommend testing that any customizations you have made to the Sugar login page continue to work on both large and small screens.

To support the new content, a new Sidecar view was added:

  • MarketingExtrasView

Two Sidecar layouts were modified to include the MarketingExtrasView:

  • LoginLayout
  • ForgotPasswordLayout

As part of the updated login page implementation, a new REST API endpoint was added to REST API version 11.2:

  • GET /login/content

Admins can choose to disable the custom content from SugarCRM on the Sugar login page. They can update the setting by navigating to Admin > System Settings > User Interface.

The marketing_extras_enabled boolean Sugar config setting has been added in this Sugar release. Setting this value to "false" will disable the custom content from SugarCRM on the login page.

Expected to Affect Few Developers

This section explains items expected to have a low impact on Sugar customizations and integrations when migrated to Sugar Spring '19 (9.0). It is expected that these items will affect few developers.

Library Updates

The following library updates and additions were included as part of this release:

  • The clipboard.js v2.0.0 library was added.
  • ruflin/Elastica was upgraded from v5.3.0 to v6.0.1. Please refer to the Elastica changelog for more details if you have custom code that calls the Elastica library directly.
  • AWS SDK for PHP (aws/aws-sdk-php) v3.55.3 was added in this Sugar release. For more information on this SDK, please visit the Amazon website.

Elasticsearch updates

This release adds support for Elasticsearch 6.2. When using Sugar with Elasticsearch 6.x, Sugar will create one search index per module instead of a single index for entire Sugar instance.

This release also adds the ability to integrate with Amazon Elasticsearch Service. Using the Amazon service does require the use of special Sugar config settings to configure AWS key, secret, and the region as seen in the example below.

'full_text_engine' => array (
   'Elastic' =>
    array (
       'transport' => 'AwsAuthV4',
       'aws_access_key_id' => '<aws access token>',
       'aws_secret_access_key' => 'aws secret access key',
       'aws_region' => 'aws region',
       'host' => 'aws ES server host',
    ),
),

EmailMarketing's time_start Property

The EmailMarketing::time_start property has been removed in this Sugar release. The start time of a EmailMarketing campaign should be derived by parsing the EmailMarketing::date_start attribute.

Updates to the Module Loadable Package Uninstaller

An option has been added to Module Loadable Package manifests that will allow Module Loader to ensure all traces of previously installed package versions (including packages that have been upgraded multiple times) have been removed.

<?php
$manifest = array(
  'id' => '<id>',
  ...
  'uninstall_before_upgrade' => true,
  ...
);

Custom pre- or post-install scripts that remove old versions of the package when upgrading may no longer be necessary when using the new 'uninstall_before_upgrade' option.

SugarCache Changes

The SugarCache implementation has been refactored to support PSR-16 cache interface and encrypted storage for multi-tenant cache use.

As part of these changes, cache backends that extend SugarCacheAbstract are deprecated and will be removed in a future Sugar release. Cache implementations from Sugarcrm\Sugarcrm\Cache\Backend\ namespace should be used instead.

Usage of the characters reserved by PSR-16 in cache keys (e.g., ( ) / @ : ) are no longer supported. When these characters are encountered, they will be converted into dash ( - ) characters and warnings are logged in sugarcrm.log.

The following Sugar config parameters have been added for SugarCache:

  • cache.backend is a string that can be used to define which caching backend class should be used.
  • cache.multi_tenant is a boolean that can be used to enable multi-tenant cache behavior.
  • cache.encryption_key can be used to define the encryption key for use in multi-tenant mode. This key will be generated automatically and doesn't need to be specified manually.

Historical Summary Updates

The translatable template string TPL_HISTORICAL_SUMMARY stored in ./include/language/en_us.lang.php now uses unescaped values. Please ensure you are not using this template in combination with Handlebars.SafeString, as this would make your code vulnerable to XSS attacks.

New ReportSchedules Module

This release introduces a new ReportSchedules module that is used to implement a new Report Scheduling feature in Summer '18. The ReportSchedules module relies on the existing SugarJobSendScheduledReport job to send reports.

./modules/Reports/schedule/ReportSchedule.php was refactored to ./modules/ReportSchedules/ReportSchedule.php. This could break customizations that were calling or overriding the ReportSchedule class directly.

Report scheduling has been migrated to a Sidecar module. This would break UI customizations that were implemented on the previous BWC report scheduling view. Developers should re-implement customizations on the new ReportSchedules module.

SugarBPM Process Definition Import Improvements

The process definition import API for SugarBPM (POST /pmse_Project/file/project_import) now supports uploads that contain all the dependent business rule and email template elements of a process definition.

REST API version 11.2 adds the selectedIds argument to the POST /pmse_Project/file/project_import endpoint. This allows clients to select what subset of SugarBPM elements should be imported from the provided .bpm file.

For more information about what changed in Sugar 9.0.x, please refer to the following related documents.

Last modified: 2019-06-11 21:33:19