Sugar 25.2 Customization Guide

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

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

User Experience Updates

Modernized Dropdown Editor

In this release, we’ve modernized the Dropdown Editor UI, transitioning from BWC to Sidecar for a cleaner, more streamlined admin experience. Admins can now manage entire dropdown lists from a single view—no more editing one row at a time.

What’s new:

• Redesigned Interface: New Sidecar layout with updated header, inline editing, and consistent list view styling. Supports dark mode.

• Formatting Flow Fix & Toggle Control: Chart colors no longer drive dropdown styling; instead, formatting is now defined at the dropdown level and pushed to charts for consistency..

  • New "Enable formatting in dropdown" toggle added per dropdown.

  • Toggle is enabled by default for: sales_stage_dom, quote_stage_dom, case_status_dom, and lead_status_dom.

  • When disabled, formatting is hidden in the UI but preserved and still used in charts.

  • When enabled, users can customize styles (colors, fonts) via the conditional formatting panel.

  • Chart colors fallback to the chart palette for items without formatting; white and black are excluded and replaced.

• Conditional Formatting: New Conditional Format Options control panel that allows users to customize the appearance of dropdown values using styles, icons, and colors.

  • The following stock/out-of-the-box dropdowns were predefined with conditional formatting for awareness and usability: sales_stage_dom, quote_stage_dom, case_status_dom, lead_status_dom

  • Formatting will be reflected as soon as saved on List View, Record View, Focus Drawer, Reports, Other components using the dropdown values, All views in sugar

  • Even if user selects RGB, we only reflect Hex number in the input

• Add New Rows: Easily add multiple items with editable fields for Display Label and Classification (for sales_stage_dom). Only completed rows are saved.

• Improved Search: Real-time search across Item Name and Display Label fields with partial match support.

• Restore to Default: Revert dropdowns to their original out-of-the-box (OOTB) state, including default sort order. Available only for OOTB lists.

• Bulk Editing & Reduced Clicks: Edit multiple rows at once and save all changes in one action.

• Sort by Display Label: New sort button allows ascending/descending sort; order persists across sessions and is saved.

• Inline Editing & Deletion: Edit Display Label and Classification fields directly; delete items with confirmation.

• Drag-and-Drop Reordering: Rearrange items via drag-and-drop. Changes are saved on click.

• Unsaved Change Warning: Users are prompted before navigating away from unsaved edits.

Note: Devs can still define custom styles (e.g., backgroundColor, textColor, icon, iconColor) for dropdown fields using extension framework (custom/application/Ext/DropdownsStyle/dropdowns_style.ext.php).

Adding support to Shared Drive files on Google Drive

The Google Drive connector for Sugar has been enhanced to support access to shared files. Users can now interact with files that are shared with them or located in Shared Drives. This includes the ability to set a Shared Drive as the root path, define variable file paths on record views, and seamlessly navigate through folders within Shared Drives. Additionally, users can switch between viewing files in "My Files," "Shared with me," and Shared Drives. If a user attempts to access a Shared Drive they do not have permission to view, a message will appear within the dashlet indicating the lack of access, with the option to navigate to an accessible area instead.

Sugar REST API updates

This Sugar release introduces REST v11_27.

Dropdown Editor

Set details of dropdown.

PUT <sugar instance>/rest/v11_27/Administration/dropdownEditor/:dropdownName

GET <sugar instance>/rest/v11_27/Administration/dropdownEditor/:dropdownName

POST <sugar instance>/rest/v11_27/Administration/dropdownEditor/create

POST <sugar instance>/rest/v11_27/Administration/package/customizations

POST <sugar instance>/rest/v11_27/Administration/package

GET <sugar instance>/rest/v11_27/Administration/package/id

POST <sugar instance>/rest/v11_27/Administration/package/remote

POST <sugar instance>/rest/v11_27/Administration/package/data

POST <sugar instance>/rest/v11_27/Administration/package/getRemotePackages

Historical Deltas API

Retrieves historical delta changes for a module based on a timestamp and list of records.

POST <sugar instance>/rest/v11_27/historically/delta

PHP Library Upgrades

Upgrade PHP libs to the latest Minor versions without breaking changes

In this release, we've updated all minor and patch versions of our PHP libraries as declared in the composer. Since these are minor and patch updates, no breaking changes are expected. The updates primarily include newly generated models and improved PHP version compatibility.

aws/aws-sdk-php             3.342.19 AWS SDK for PHP - Use Amazon Web Services in your PHP project
doctrine/dbal               3.9.4    Powerful PHP database abstraction layer (DBAL) with many features for da...
egulias/email-validator     4.0.4    A library for validating emails against several RFCs
guzzlehttp/guzzle           7.9.3    Guzzle is a PHP HTTP client library
laminas/laminas-escaper     2.16.0   Securely and safely escape HTML, HTML attributes, JavaScript, CSS, and URLs
league/oauth2-client        2.8.1    OAuth 2.0 Client Library
microsoft/microsoft-graph   2.29.0   The Microsoft Graph SDK for PHP
rector/rector               2.0.11   Instant Upgrade and Automated Refactoring of any PHP code
rlanvin/php-rrule           2.5.2    Lightweight and fast recurrence rules for PHP (RFC 5545)

PHP-Parser

Sugar utilizes a PHP library called PHP-Parser Its purpose is to simplify static code analysis and manipulation.

There are major internal changes in this library, if you use them, please refer to this library’s upgrade procedure here.

nikic/php-parser → ^v5.4.0

JS Library Upgrades

@babel/core -> 7.27.4
@sugarcrm/ventana -> 1.1.19
handlebars -> 4.7.8-sugarcrm
babel-loader -> 9.2.1
bootstrap  -> 5.3.7
gulp -> 5.0.1
jquery-migrate -> 3.5.2
sinon -> 21.0.0
tailwindcss -> 3.4.17
underscore -> 1.13.7
webpack -> 5.99.9
eslint-plugin-import -> 2.31.0
cure53/DOMPurify -> 3.2.6
stylelint-config-standard -> 38.0.0

Supported Platforms Update

Support for OAuth 2.0 token-based authorization with Exchange Online and Sugar email functions

Configurability updates

Improved Control Over Field Updates by Process Definitions

We are enhancing the control over the fields that can be modified by Process Definitions. By default, only fields that are visible in the user interface will be eligible for updates. Fields not exposed on the frontend will no longer be modified automatically by these processes, in other words, if the field is available to be added to any UI it means it is exposed, doesn't necessarily mean it has be in a Record View for example.

For teams needing more specific behavior, it’s now possible to configure a denylist of fields that should not be updated by Process Definitions. This provides greater flexibility and precision in how automation interacts with your data. You can define this using a new $sugar_config setting. For example, the configuration below prevents field_to_block_1 and field_to_block_2 in ModuleName1 from being updated by Process Definitions:

$sugar_config['bpm_denylisted_fields'] = [
  'ModuleName1' => ['field_to_block_1', 'field_to_block_2'],
  'ModuleName2' => ['another_field_to_block'],
];

Note: When this sugar_config is set, only the specified fields will be blocked — regardless of their visibility in the user interface.

Sugar Config Settings

Removed Functions / Libraries / Features

Removal of Legacy Modules Metadata Extension Path

As part of our ongoing efforts to modernize Sugar Core, this release removes support for the legacy include/modules_override.php file path used for module metadata customizations. This path was used in versions prior to Sugar 6.3.x but is no longer recommended or necessary. You should be using the supported Extensions Framework with the Include extension for all metadata customizations.

A new healthcheck bucket 'F' (manual customization) has been added to ensure compatibility to this version.

Removal of Unused Platform

As part of ongoing SugarCore cleanup efforts, the kiosk platform has been removed to streamline with our products and services.

Removing gulp-filter JS lib

The gulp-filter library has been removed from the project after verifying it was only used in a single instance within a Gulp task. Its functionality has been replaced with a native filter function applied directly within the stream. This change retains the original filtering logic and preserves the existing behavior and output of the task.

Removing uglify-js and socket.io JS lib

Removed the legacy socket.io dependency from package.json as it was no longer used anywhere in the codebase. This also removed its transitive dependency uglify-js.

Data Changes

New Indexes for Calls and Meetings

To enhance the performance of queries involving Calls and Meetings using our FilterApi, we’ve added new indexes to the corresponding module definitions (vardefs). These indexes are designed to optimize data retrieval on such modules by our FilterApi:

• idx_calls_series_event_deleted 
  • 'series_deleted', 'event_type', 'deleted
• idx_calls_date_mod_rep_parent_id - 
  • 'date_modified', 'repeat_parent_id

Platform Updates

Scheduler Jobs Now Run on a Consistent Timezone

In this release, we've implemented a long-awaited enhancement that brings consistency to scheduler job execution times. Previously, job execution depended on the timezone of the scheduler's assigned user. As Sugar automatically updates user timezones—and admin users might share credentials across different locations—this led to jobs running at different times.

With this update, scheduler jobs now run based on a centralized (UTC), consistent timezone, eliminating timezone-related surprises and ensuring reliable, predictable behavior.

• In the Scheduler UI, execution times are shown in your local timezone, so you always know exactly when it will trigger—no mental math required.

• Existing schedulers remain unchanged, but we now clearly display their scheduled times based on your profile’s timezone.

Enhanced SystemProcessLock Handling to Prevent Redundant Execution During Admin QRR

Resolved an issue where regular user requests could unintentionally trigger cascading expensive operations, such as metadata and language cache rebuilds, during or immediately after an admin-initiated Quick Repair & Rebuild (QRR). Previously, when cache files were deleted by an admin QRR, regular users encountering missing cache would queue behind a system-level lock and subsequently attempt to perform the same rebuild operations once the lock was released. This behavior caused unnecessary server load, timeouts, and a degraded user experience.

With this enhancement, the lock handling logic has been updated to prevent non-admin users from executing expensive operations when the lock cannot be acquired. Instead, such requests will now safely return without action, ensuring that only admin users can initiate these processes. This significantly reduces server load and improves system responsiveness during cache rebuilding scenarios.

Improved Deep Linking Support for SugarCRM on Mobile Devices

In this release, we have implemented improvements to the experience of opening Sugar links from mobile devices. This update addresses inconsistent behaviors when accessing CRM links from email or messages, ensuring a more predictable and seamless user journey on both Android and iOS platforms.

What's new:

• Universal Link Support: SugarCRM mobile app now uses Universal Links (iOS) and App Links (Android) to seamlessly redirect users from supported emails/messages directly into the app—bypassing the mobile browser when possible.

• Smart App Prompts: Users without the SugarCRM mobile app installed are now prompted to download it from the App Store or Google Play when tapping a SugarCRM link.

• Improved Workflow Link Behavior: Links generated from workflows (e.g., SugarBPM) now attempt to open in the app rather than defaulting to the mobile browser.

• Browser Consistency Fixes: Addressed inconsistent behavior across third-party browsers (e.g., Edge, Chrome) especially on iPhone, ensuring reliable app-switch prompts.

Note: Support for this feature on custom or on-premise domains requires configuration changes and updates to the Mobile App to include those domains. Customers should contact support for implementation guidance.

Enhanced Content Security Policy (CSP) for Improved Application Security

As part of our ongoing commitment to application security, we are introducing Strict Content Security Policy (CSP). This policy significantly reduces the risk of malicious script execution by restricting the sources from which scripts can be loaded.

To support this enhancement, we’ve refactored the frontend code to:

• Remove inline event handlers and javascript: URIs

• Add nonce attributes to all <script> elements

These changes ensure that only trusted scripts are executed in the browser.

This feature is configurable via App.config ($sugar_config['features']['enableStrictContentSecurityPolicy']) and requires a QRR after being toggled.

The rollout will follow a phased approach, beginning in report-only mode to monitor violations, with full enforcement to follow in both core and customization layers in future releases.

Declarative Metadata Refactoring

As part of our ongoing efforts to make Sugar's metadata fully declarative and serializable, this release includes the first phase of refactoring non-declarative components within Sugar Core. Previously, some metadata included conditional logic that needed refactoring. We’ve begun restructuring some areas to align with a declarative format, laying the groundwork for the new Metadata generation we've discussed here.

Replace the TCPDF with SugarPdf in MapsGenerator

In this release, we've updated MapsGenerator.php::createPDF() to use SugarPDF instead of directly using TCPDF.

Added Backend Framework for Dropdown Classifications

In this release, we've introduced backend support for a generic dropdown classification framework as part of the Dropdown Editor enhancements. This replaces hardcoded logic (e.g., sales_stage_dom) with a scalable, metadata-driven approach, enabling configurable mappings between dropdown values and classification categories..

Key details:

• Classifications are defined using metadata and stored via the extension framework.

• A classification includes:

  • A unique identifier

  • Translatable classification options (app_list_strings)

  • Mappings between dropdown values and classification categories

• No API or UI changes in this implementation — a helper class is provided to handle loading and saving classification data.

• Designed to support future use with multiple classifications per dropdown.

Note: This implementation does not expand classifications to all dropdowns yet, sales_stage_dom only

Prevent Data Loss on Market MLP Uninstallation and upgrade

In this release, we're addressing a critical issue where upgrading to Market MLP version 25.1 resulted in unintended data loss, specifically affecting connector setting configurations that were expected to persist through the uninstallation process. Additionally, the upgrade mechanism has been improved to ensure proper cleanup of residual files and directories from previous installations, which previously caused version conflicts, broken dependencies, and unexpected behavior in the new version. These enhancements ensure a smoother and more reliable upgrade experience..

Note: If on upgrade customer does not have active market license then the features would not show up after upgrade even if they have MLP installed.

SugarLive compatibility with the V2 console for Amazon Connect

For SugarLive, Sugar provides SugarServeSampleBot.zip which was only compatible with the Amazon Lex V1 console. However, in Amazon Connect, there is a warning about the Lex V1 console being discontinued after September 15, 2025. We have now implemented and updated the SugarServeSampleBot.zip file to make it compatible with the V2 console.

Bug Fixes

• Fixed an issue with the FilterApi that was returning extra fields in the response payload even when filtering by using args fields.
• Fixed QRR Occasionally Fails to Rebuild Module/Class Cache, Causing Outages and UI Errors caused by race conditions during concurrent or overlapping QRR executions or user requests during cache rebuild.
• Fixed an issue for a specific scenario where user licenses were failing to update
• Fixed an issue that a calculated field using the countConditional function in combination with a relate field (e.g. countConditional($notes,"name",createList("test"))) caused a “Too many tables” error when a large number of one-to-one relationships were created between modules
• Fixed an issue on Uncaught TypeError: Sugarcrm\\Sugarcrm\\Security\\Escaper\\Escape::html() caught on upgrade from 14.0.1 to 25.1 
• Fixed an issue where Sugar Automate licenses and UI elements disappear after manual license validation and only reappear when an online validation is performed.
• Fixed an issue with our silentUpgrader that, in some cases, the healthcheck was still executed during the upgrade even if the instance was configured with “Bypass Healthcheck” option enabled.
• Fixed an issue where People names (Contacts, Leads, Users) currently do not have a display option for how names are traditionally written in Chinese. The LastFirst name format has been added to the default list to support proper name display across the product (e.g., Contacts list view, record view, Lead, and Assigned To fields)
• Fixed an issue on the Case Summary Chart and Opportunity Metrics Chart (migrated from Sucrose to Chart.JS) where, if only one label was present, it displayed at the bottom of the chart in a space too small to display it properly
• Fixed an issue where Users were receiving a permission error when trying to use Doc Merge for Quote records and have {currency_name.iso4217} in the template.
• Fixed an issue where regular users triggered redundant rebuilds after admin QRR due to SystemProcessLock, causing server overload due to multiple expensive operations running simultaneously.
• Fixed an issue where Generating a Quote from the Revenue Line Item detail view doesn't allow the generated Quote to be saved.
• Fixed an issue where Update Momentum of In-Progress Smart Guides' scheduler fails on NULL score or point values.
• Fixed an issue where a single email failure due to a Laminas error could halt the entire import scheduler, leaving the email unread and causing repeated failures.
• Fixed an issue where Developer user encounters error when editing Timeline. Developer only users will not see this option but users with Admin and Developer access will.
• Fixed an issue when a user has a profile date format that is not ISO compliant, the date outputted into a PDF is not valid in ISO format, Sugar was using current date but should interpret that date correctly.

Sugar Core Security Updates

As part of our ongoing efforts to keep Sugar clean, fast, reliable, and most importantly secure, we have updated Sugar Core code in different areas of the application such as Package Scanner, Studio, Module Installer, UI rendering, API endpoints, Legacy SOAP API, File Uploads, Portal, PII Fields, ACL rules, Legacy Workflows, Smart Guides, HTTP Headers and BWC modules. Not only those changes but we've cleaned up and improve our logging messages around deprecations.