Sugar 11.2 (Q4 2021) Customization Guide

The purpose of this document is to provide insight to Sugar Developers for adapting custom Sugar code, extensions, and integrations to the Sugar 11.2 (Q4 2021) release. This guide provides an overview of some of the new features and identifies changes in Sugar 11.2 (Q4 2021) that could cause an immediate impact on Sugar customizations and integrations built for earlier Sugar versions.

Please check out the Q4 2021 Developer Webinar recording for more developer highlights. For Admin and End User release notes, please visit the Sugar 11.2.0 Release Notes.

User Experience Updates

Support for Dark Mode

Dark mode is now available in Sugar. Users have the ability to choose their theme preference by going to their user settings and selecting Use System Settings, Light, or Dark mode in the “Appearance” field. On upgrade, user instances will default to Use System Settings, which will follow the mode the user has selected in their operating system. Sugar Admins can also provide dark and light themed logos under the System Settings panel.

If you have Sugar UI customizations then you should test how they appear in dark mode to ensure acceptable color contrasts and that images display properly. In particular for images, you may need to provide alternative image files for light vs. dark mode. Here's some tips for working with images.

Double click to inline edit list

If a user had edit permission, then double clicking on a record in a list will now toggle edit mode. If you've customized a list view to support double click actions, you should test that this change is not conflicting.

New SugarIcon documentation in Styleguide

SugarIcon documentation has been added to the Styleguide. Developers should be able to reference the list of supported icons and usage instructions under Admin > Styleguide > Base CSS > Icons.

Save & Validation for Opps to RLI Cascade During Create

When editing an opportunity, Sugar validates and will not allow users to check the cascade boxes if they have no eligible RLIs. During create, Sugar allows users to check the boxes and put in values when there are no eligible RLIs to prevent them having to add all their RLIs before being able to input info at the opportunity header level. A validation has been added to warn them if they end up not adding eligible RLIs.

SugarPredict icons on Opps and Leads prediction fields 

Sugar Sell now presents SugarPredict icons onto prediction fields. This icon is present in all views: list view, record view, list view dashlet, record view dashlet (including single-record tabs and list tabs), preview, and subpanels. Sugar uses SugarIcon font in @purple and its name is “@sicon-sugar-predict”. Those icons are present in all list views, record view 

Create custom Focus Drawer dashboards 

Users can create and switch between custom focus drawers depending on team or module access per Team/Module. Dashboard owners can pin to top, create, duplicate, delete, and add a dashlet from the FAB menu. Non-owners can pin to top, create and duplicate dashboard from the FAB menu. 

Product Catalog Record View update in Dashlet

Admins can control what fields appear on the top drawer when viewing a product catalog item by clicking the icon in the PC dashlets, therefore now the drawer that opens to let users view a catalog item from those dashlets respect the Product Catalog record view layout. Before, it was its own layout that wasn’t configurable. 

Show only Active items in Product Catalog dashlets 

The Product Catalog and Product Catalog Quick Picks dashlet allow the users to easily access and instantly add line items in Quote’s Worksheet and Opportunities respectively, which is great for quick access. Now they will only display catalog items with an “Active” status beneath them. Categories with items that are all in “Inactive” Status, will be hidden. 

Show Escalated field on various views

Sugar will indicate via Escalated field/badge in various views (record view, list view, record view dashlet, preview view and list view dashlet) for any module that escalation is enabled. 

Remove attachments from Notes list view

Sugar is removing attachments from the Notes list view, only parent Notes would now show up and not the child attachments on the notes list.

Added filter on timeline dashlet

Sugar has added a filter in the timeline dashlet as well as sub-panels. Now users can use this filter to easily get to the list of interactions or updates that they are looking for.

Changes to the Product Catalog Record View layout via Studio

Before this release, changes to the Product Catalog Record View layout via Studio did not show up when viewing records from the Product Catalog Dashlet. Admins can now control what fields appear on the top drawer when viewing a product catalog item by clicking the icon in the PC dashlets.

Sugar REST API updates

This Sugar release introduces REST v11_14.

SOAP get_module_fields method is broken after upgrade to 11.1.0

The get_module_fields SOAP method has been fixed in this release and now returns the SOAP envelope as expected.

Module Loader installation progress API

This API is not designed for multi user or parallel usage and works exclusively for a single admin user. In case when a module is not currently installing the API will return the empty or the previous installation results for a given package. Thus using the API not during installation is useless.

PHP Library Upgrades

Smarty

Sugar utilizes a PHP library called Smarty for rendering PDFs in PDF Manager and also for rendering HTML pages used by Backwards Compatibility (BWC) modules. In Sugar 11.2 (Q4 2021), we will be upgrading that library from v2.6.11 to the latest version v3.1.35. There have been significant changes from Smarty 2.x to 3.x and because it is a major version upgrade there are some potential for breaking changes. The upgrade process will scan and identify incompatibilities and attempt to fix those Smarty templates. If it identifies an incompatibility that it can not automatically update then the upgrade will not proceed.  See the dev blog for more details.

Symfony Components

Symfony is a leading PHP framework that provides a set of common components. For example, the Symfony Security Component is used by Sugar for input validation. We've updated these libraries to latest patch versions and removed some transitive dependencies.

symfony/cache 3.4.16 → 3.4.47
symfony/console 3.4.16 → 3.4.47
symfony/framework-bundle 3.4.16 → 3.4.47
symfony/security-core 3.4.16 → 3.4.47
symfony/security-csrf 3.4.16 → 3.4.47
symfony/translation 3.4.16 → 3.4.47
symfony/validator 3.4.31 → 3.4.47
symfony/process 3.4.11 → 3.4.47
symfony/http-kernel N/A → 3.4.47

Wikimedia Less.php

Wikimedia Less.php is a LESS compiler library written in PHP that has been upgraded to the latest available version in this release. This update is compatible with latest PHP versions. Check out the CHANGELOG for details.

wikimedia/less.php 1.8.2 → v3.1.0

Google PHP Client

Google API Client library enables Sugar to work with Google APIs such as Gmail, Drive or YouTube. There are major internal changes in this library, if you use them, please refer to this library’s upgrade procedure here.

google/apiclient 1.1.4 → 2.9.2

Microsoft Graph SDK

Microsoft Graph SDK for PHP provides Sugar with a framework for retrieving data from a Microsoft account using the Microsoft Graph API via OAuth2 tokens. There are no known breaking changes in this upgrade, they are mostly newly generated modes and PHP version support.

microsoftgraph/msgraph-sdk-php 1.13.0 → 1.33.0

PhpMailer

PhpMailer provides Sugar with a full featured email transfer class for PHP. All breaking changes are documented in the CHANGELOG.

phpmailer/phpmailer v5.2.22 → v6.5.0

AWS SDK PHP

The PHP library that Sugar uses for interacting with AWS web services has been upgraded. Check out the CHANGELOG for more details.

aws/aws-sdk-php 3.55.3 → 3.183.13

The following packages were upgraded as transitive dependencies.

guzzlehttp/promises 1.3.1 → 1.4.1
guzzlehttp/psr7 1.6.1 → 1.8.2
mtdowling/jmespath.php 2.5.0 → 2.6.0
symfony/polyfill-mbstring 1.15.0 → 1.23.0

Doctrine DBAL

Doctrine DBAL provides Sugar with a powerful database abstraction layer with many features for database schema introspection, schema management and PDO abstraction. There are no breaking changes that may affect Sugar and has most of the deprecations documented in the form @deprecated annotations or in the form of runtime deprecations (disabled by default, see https://github.com/doctrine/deprecations and https://github.com/doctrine/dbal/blob/2.13.x/UPGRADE.md). There is a new SugarConfig option that provides additional logging for the use of deprecated Doctrine functions.

doctrine/dbal 2.12.1 → 2.13.2

JS Library Upgrades

jQuery and Underscore

A couple of core Sidecar JS libraries have been upgraded to latest available versions in this release. Underscore and jQuery are two heavily used libraries in Sugar customizations. There are no known breaking changes in these upgrades, they are minor or patch version bumps. The jQuery version upgrade just includes bug fixes. The Underscore library upgrade adds some new helpers and bug fixes..

jQuery 3.5.1 → 3.6.0
jQuery Migrate 3.3.1 → 3.3.2
Underscore 1.9.1 → 1.13.1

Amazon Connect Libraries

The Amazon Connect Streams and Amazon Connect Chat JS library (ChatJS) are core SugarLive libraries. There are no known breaking changes in these upgrades which include bug fixes and enhancements.

amazon-connect/amazon-connect-streams 1.4.9 → 1.6.9
amazon-connect/amazon-connect-chatjs 1.0.6 → 1.0.8

big.js

big.js provides Sugar with a small, fast JavaScript library for arbitrary-precision decimal arithmetic. All breaking changes are documented in the CHANGELOG.

big.js 3.1.3 → 6.1.1

Configurability updates

Sugar Logic

Sugar Catalog Server

When creating a new instance of 11.2.0 and above, Sugar catalog server is enabled and set to the catalog url of `https://appcatalog.service.sugarcrm.com` irrespective of the instances' regions. This story is to change that catalog url to be region specific url based on instances' regions . 

In 10.3 we added an upgrade script for IDM-only instances to set System Settings' catalog_enabled flag to true and set the catalog_url to the region-specific Catalog URL for the instance’s region. Here we added that same functionality to the Install process so new instances being added to the Cloud will have the same config settings set. 

SugarBPM

Call sentiment fields are now displayed and evaluated as Positive, Neutral, or Negative instead of a decimal value.

Studio

Sugar Config Settings

Removed Features

Removal of facebook-php-sdk

The Facebook-php-sdk (facebookarchive/facebook-php-sdk) is stored at ./include/externalAPI/Facebook/FacebookLib.php. The API that uses this SDK is not used in Sugar since 2014 and not compatible with current Facebook APIs, therefore it has been removed in this release.

Remove support of MD5 hashing for authentication purposes

Since md5 hashes for authentication is no longer supported and forgot password feature successfully updates user_hash in the database. After the upgrade to SugarCRM 11.2 config option $sugar_config['passwordHash']['allowLegacy'] will have no effect.

Data Changes

Added Active Status field in Product Catalog

A new active_status field has been added to Product Catalog module. It is a drop-down field with 3 default options: Active, Inactive, Retired. This identifies if the product is actively available for sale, temporarily unavailable and therefore inactive, or retired when the organization no longer sells this product.

Added "processed" to list of reserved field names

In this release, Sugar is now reserving the “processed” field name in addition to other reserved field names like "id" and "parent_name". This was necessary to prevent issues with logic hook handling. If your Sugar instance uses the “processed” field name, then you will have to change to use a different field using an un-reserved field name. 

Product Catalog Status field using Search and Select

A new attribute has been added to the vardefs for modules. Devs can now make a code change (nothing you can do in studio) to add a default_relate_filter to a module. This allows devs to set an initial filter when going to Search & Select per module.  

When populating Product Catalog Relate fields using Search and Select, default a visible filter for “Status is Active” that can be changed by the user to access items that are in different statuses, including inactive.  

Note: The only way a user can access an inactive product catalog item, is by using Search and Select. 

1. e.g When creating an RLI with an item that’s inactive, the user has to select Search and Select and kill the default “Status is Active” filter.  

Filesystem Changes

Ex. Changes to Sugar filesystem structure.

Platform Updates

Documents and Document Merges (formerly known as WDocs)

We added formerly known WDocs to Core Sugar. A common need among Sugar users is the ability to create letters, contracts, proposals, etc. Documents can be used to quickly create Microsoft Word templates that can be used to merge information from any module in Sugar.

Documents is available for Sell and Serve only. We created Documents Template, a new module where users can store and edit their Document Templates that will be used for document merges. This is different from the original WDocs where templates lived in the Documents module. Documents Template can be configured via studio, but it’s a special module in that it can’t be used to create relationships with other modules that would result in displaying Documents Templates as a subpanel in other modules.

In addition to the Documents Template module, another module called Document Merges was created. Document Merges is backend module that is not visible in studio to any user. This module keeps information on the current merges and it is used as the primary point of data exchange with the documents microservice and repository for merge status and logs. Document Merges data is served through the Documents widget, which is visible in the bottom right hand corner of a user’s Sugar instance.

We added “Merge to Doc” and “Merge to PDF” to these different layouts: Record View, List View, and Subpanel Action menus.  Selecting Merge template results in a MS Word doc and selecting Merge template to PDF results in a PDF document. Merge template and Merge template to PDF will also appear in the newly added “Action Buttons” for easier access

Calendar (formerly known as wCalendar)

Calendar, formerly known as wCalendar is a customizable calendar solution that displays a Sugar module on a calendar. One of main things to highlight is the calendar can be used with any SugarCRM module, including future custom ones deployed by users. In addition to viewing calendar in Sugar, users can embed calendars in Records and dashlets. This new Calendar will replace the default SugarCRM calendar page. This new Calendar Center’s UI will be rendered by a 3rd party Kendo Scheduler widget. The third party’s source code will be added to Sugar’s vendor library to make this work.

Users can publish or export their calendar using the Calendar Export option to export their Calendar as an ICS file or choose the Calendar Publish option and paste the URL in their email client. Users can also export their calendar as a PDF file for viewing offline

Created a new custom UI for the CAlendar’s module. Email Templates in the Calendar are going to resemble the Process Email Templates pattern in the fields. Under Settings, in filter, we used the default Sugar filter.
This allows users to filter the events to show for a specific Calendar definition Record and weeds out the unrelated ones. The modules that appear in the filter are dynamically generated to only show ones that contain data.

Note: unlike wCalendar, this calendar will not support various themes and will only be available in the main Calendar Center, not in LVs and Subpanels.

Smarty - Health check routes the upgrade process

New functionality in 11.2 Upgrader Healthcheck, which scans for Smarty customizations that have a syntax that will break with 11.2 upgrade (Smarty 3). When Healthcheck identifies any such instances, it outputs a Bucket F error and upgrade is not able to proceed as well as outputs the specific .tpl file in the Bucket F error. 

Smarty Upgrader Script - Upgrader tool to automatically update known syntax issues of customer instances

This script also attempts to programmatically update custom .tpl files to avoid conflicts between Smarty version 2 and version 3.1.34. The script includes output about the successes and failures in these conversions.

Note that this script will be included as part of 11.2 upgrade.The script should find all the .tpl files inside the target directory and convert their syntax to be compatible with Smarty3.

Allow upgrades with version 4.6+ to be installed for RT SalesMap

Healthcheck now allow list containing RT SalesMap v4.6+. Module vendors should be consistent with versioning schema being used for a module. The recommended one is Semver Semantic Versioning 2.0.0, may be prefixed with v letter, e.g. 3.14.15, v0.2.0. If a module already uses different schema - stick with existing one to keep consistency. 

Prune tracker table scheduler frequency and configuration policy

Tracker Pruner job scheduler is changed to be executed every day instead of once a month.

Triple curly braces

SugarFields has triple curly braces in templates, like { {{$var… which will be compiled into another template with { $var… but new Smarty doesn’t support spaces between the curly brace and dollar sign.

replace:

{ {{sugarvar  key='options' string=true}}[{{sugarvar key='value' string=true}}]}

with:

{assign var="field_options" value={{sugarvar key='options' string="true"}} }
{assign var="field_val" value={{sugarvar key='value' string="true"}} }
{$field_options[$field_val]}

Sugar Portal update to utilize Content Security Protocol

As of 11.2.0, Ent/Sell/Serve will no longer ship with an index.html file and will instead ship with, and use, index.php so that the portal can leverage the content security policy (CSP) that is inherent to the security of the Sugar platform.

Clickjacking prevention with Content-Security-Policy improvements

To prevent Clickjacking attacks SugarCRM uses Content-Security-Policy that was introduced in 11.0 System - SugarCRM Support Site . SugarCRM utilizes frame-ancestors directive to specify valid parents that may embed a page using <frame>, <iframe>, <object>, <embed>, or <applet>. OOTB frame-ancestors directive is set to 'self' and can’t be overwritten in the Admin panel at the moment.

Deprecated functions

Deprecated use of FontAwesome 

Sugar has added a HealthCheck Scanner to search for “fa-*” customizations and notify Admins that they need to fix their code by the release where FontAwesome will be removed. The message is: “FontAwesome is deprecated as of 11.2 and will not be supported in 12.0. Use of FontAwesome detected in: `%s`.” 

PHP stable sort deprecation

PHP stable sort functions library (vanderlee/php-stable-sort-functions) provides stable sort utility methods and standalone functions.  This library is not currently in use by Sugar so it is being deprecated in this version and soon to be removed. But we did update it to latest patch release (v2.0.5) with no expected breaking changes.

Doctrine DBAL deprecation warnings

In the future, Sugar will move to Doctrine DBAL 3.x which removes some deprecated functionality. In order to find and upgrade the usage of this functionality, you should enable runtime logging of calls to deprecated Doctrine DBAL functions.

$sugar_config['dbal_deprecation_log'] = true; // enable log

$sugar_config['logger']['level'] = 'info'; // set appropriate logging level

Backtrace can be attached to log entries in order to locate the exact source code lines that need to be changed.

GET /Administration/aws - getAWSConfig - Gets configuration settings for Amazon Web Services integrations 
POST /Administration/aws - setAWSConfig - Sets configuration settings for Amazon Web Services integrations 
POST /Administration/csp - setCSPConfig - Sets configuration settings for Content Security Policy 
GET /Administration/csp - getCSPSConfig - Gets configuration settings for Content Security Policy