Sugar 26.1 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 26.1 release. This guide focuses on changes in Sugar 26.1 that could cause an immediate impact on Sugar customizations and integrations built for earlier Sugar versions.

For Admin and End User release notes, please visit the Sugar 26.1.0 Release Notes.

Sugar REST API Updates

This Sugar release does not introduce a new REST API version. Both 25.2.0 and 26.1.0 expose v11_27 as the maximum supported version. Do not update integration code to reference a new version string.

Pagination Change in FilterApi

next_offset in FilterApi list responses now returns -1 when the id_query code path determines there are no further pages of results. Previously next_offset was always a calculated positive integer even on the last page. This change applies only to the id_query code path inside FilterApi — queries not using id_query are unaffected.

What to do: Update pagination logic to treat next_offset === -1 as the end-of-list signal. Do not pass the returned next_offset directly as the next request's offset without first checking for -1.

New Endpoint — Teams Filter

A new dedicated filter endpoint for the Teams module is now available:

GET <sugar instance>/rest/v11_27/Teams?filter=...

The endpoint extends FilterApi with a custom join to the users table. Results include teams whose associated user has status = 'Active', as well as teams with associated_user_id IS NULL. This is additive — no existing endpoint is replaced or changed.

RelateRecordApi — Users Relationship Field Restriction

Previously, restricted field population (erased_fields, limited $userFields) was applied only when traversing the aclroles relationship link to the Users module. This guard has been removed. The restriction now applies to all relationship links where the related module is Users.

Affected endpoint pattern:

GET <sugar instance>/rest/v11_27/{Module}/{id}/link/{any_users_link}

Responses for any Users-module relationship traversal now return a reduced field set with erased_fields applied, matching the behavior previously only seen on aclroles.

What to do: Audit all integration code that traverses relationship links to the Users module. Ensure your integration handles the reduced field set and respects erased_fields in the response.

UsersApi — Field-Level ACL Enforcement on Record Retrieve

GET /rest/v11_27/Users/{id} now enforces field-level ACL permissions when a fields parameter is present. If the calling user lacks access to any requested field, the endpoint returns HTTP 404 Not Found. Fields most commonly affected: user_hash, system_generated_password, is_admin, portal_user_password.

What to do: Remove sensitive password and privilege fields from fields parameters in Users API calls. Only request fields the API consumer has explicit permission to access.

UsersApi — Duplicate Username Error Code Change

When a duplicate username is submitted during user creation, the HTTP status code changed from 403 Forbidden to 422 Unprocessable Entity. In 25.2.0, User.php threw SugarApiExceptionNotAuthorized (HTTP 403). In 26.1.0, UsersApi::createUser() catches that exception when the label is ERR_USER_NAME_EXISTS and re-throws it as SugarApiExceptionInvalidParameter (HTTP 422). The error key ERR_USER_NAME_EXISTS is unchanged.

What to do: Update any code that checks for HTTP 403 to detect duplicate usernames — change to 422.

Cache-Control Headers on All API Responses

All API responses now emit the following headers by default:

Cache-Control: no-store, no-cache, must-revalidate
Pragma: no-cache
Expires: 0

Previously, only error responses carried Cache-Control: no-store. Successful responses had no cache directive. CDNs, reverse proxies (Varnish, Nginx cache), browser Service Workers, and integration middleware that previously cached Sugar API responses will be affected.

Custom API routes that legitimately benefit from caching must now explicitly opt in by adding 'cacheEtag' => true to their route definition:

$routes = [
    [
        'name'      => 'MyCustomEndpoint',
        'path'      => '/MyModule',
        'method'    => 'GET',
        'shortcut'  => false,
        'cacheEtag' => true,
    ],
];

FilterApi — $contains Warning on Relate Fields

Using the $contains filter operator on relate or assigned_user_name field types now triggers a PHP E_USER_WARNING. The query still executes but the warning is logged.

What to do: Migrate $contains filters on relate fields to the $in operator.

IDM Mode — Portal and Group Users Now Deletable via API

In IDM-enabled environments, portal-only users (portal_only = true) and group users (is_group = true) are now exempt from the IDM deletion restriction and can be deleted via the API. Regular domain users remain non-deletable via API in IDM mode and must be managed through the identity management system.

Supported Platforms Update

• PHP Support
  • We are dropping support for PHP 8.3 and adding support to PHP 8.5
  • There isn't an upgrade path from 8.3 to 8.5, you must ensure it follows the upgrade path 8.3 -> 8.4 -> 8.5
• MySQL Support
  • We are dropping support for mysql 8.0.40
  • Keep support for MySQL 8.4.3
• MSSQL Support
  
  • Keep support for MSSQL 2022
• Oracle Support
  • Keep support for Oracle 19
  • We are dropping support for Oracle 23
  • Adding support for Oracle 26 (note that Oracle 26 is Oracle 23.26)
• DB2 Support
  • Keep support for DB2 11.5.9
  • Adding support for DB2 12.1
• Search
  • Keep support for Elasticsearch 8.x
  • Adding support for Elasticsearch 9.x
  • Drop support for OpenSearch 2.7
  • Keep support for OpenSearch 2.19
  • Adding support for OpenSearch 3.x

PHP Library Upgrades

New Dependencies

The following packages are new direct dependencies in 26.1.0:

webklex/php-imap             6.2.0    Email / IMAP protocol support
illuminate/collections       v12.50.0 Laravel Collections utility
illuminate/support           v12.50.0 Laravel Support helpers
illuminate/pagination        v12.50.0 Laravel Pagination
nesbot/carbon                3.11.1   Enhanced datetime handling
symfony/polyfill-php83       v1.33.0  PHP 8.3 polyfills
symfony/polyfill-php84       v1.33.0  PHP 8.4 polyfills
symfony/polyfill-php85       v1.33.0  PHP 8.5 polyfills
symfony/translation          v6.4.32  Translation component
psr/clock                    1.0.0    PSR-20 clock interface
doctrine/inflector           2.1.0    String inflection

phpseclib/phpseclib was an indirect dependency in 25.2.0 (version 3.0.43) and has been promoted to a direct dependency in 26.1.0 (version 3.0.51). A security vulnerability in this library was also resolved in this release (SUS-618).

doctrine/cache 2.2.0 has been removed and replaced by the cache abstraction layer.

Major Version Bumps

The following packages received major version bumps. Review any custom code that interacts with these libraries directly:

firebase/php-jwt      7.0.0 (aliased as 6.11.0 in composer.json — low risk)
doctrine/lexer        3.0.1 (may affect custom query/annotation parsing)
ezimuel/guzzlestreams 4.1.0 (verify custom HTTP stream usage)

Notable Version Updates

microsoft/microsoft-graph    v2.56.0
onelogin/php-saml            3.8.1
google/apiclient             v2.19.0
aws/aws-sdk-php              3.374.2
guzzlehttp/guzzle            7.10.0
monolog/monolog              3.10.0
onelogin/php-saml            3.8.1

JS Library Upgrades

No JavaScript library changes were made in this release.

Supported Platforms Update

PHP 8.5 Support Added

Sugar 26.1 adds support for PHP 8.5.x. The minimum supported version (PHP 8.2.0) is unchanged.

PHP 8.5 support is enabled by the new symfony/polyfill-php83, symfony/polyfill-php84, and symfony/polyfill-php85 packages included in this release.

Developers running PHP 8.4+ should audit custom code for PHP 8.4 deprecations, including implicitly nullable parameters and null passed to non-nullable parameters in internal functions.

Support for OAuth 2.0 Token-Based Authorization with Exchange Online

Sugar now supports sending emails via Microsoft Exchange Online using OAuth 2.0, in alignment with Microsoft's announcement to permanently disable Basic Authentication for SMTP AUTH. When an outbound email account is configured using Microsoft OAuth 2.0, Sugar sends emails through the Microsoft Graph API instead of SMTP.

A new token provider class CustomGraphPhpLeagueAccessTokenProvider.php in include/externalAPI/MicrosoftEmail/ handles refresh-token persistence and EAPM record cleanup on error. Custom Microsoft integrations can leverage the callback-based token update lifecycle in this provider.

To enable this functionality, administrators must register an application in Azure with the necessary API permissions (Mail.Send, Mail.Read, IMAP.AccessAsUser.All, offline_access) and configure the Microsoft connector in Sugar. This transition will occur automatically for existing Exchange Online OAuth accounts, but users will need to re-authorize their email accounts in Sugar.

Note: This improvement has been backported to Sugar 25.1.x.

Configurability Updates

New Sugar Config Settings

All Prune Database keys are optional — existing deployments do not need to set them.

Removed Functions / Libraries / Features

Removed JavaScript Files

Two JavaScript files present in 25.2.0 are completely absent in 26.1.0:

include/javascript/phaser/phaser-sugar.min.js — The Phaser game engine has been removed. Any custom module, dashlet, or Sugar7 plugin referencing the Phaser global will throw a JavaScript error at page load.

include/javascript/sugar7/plugins/CanvasDataRenderer.js — The canvas-based data chart rendering plugin has been removed. Any custom code calling App.plugins.load('CanvasDataRenderer') will fail at load time.

What to do: Remove all Phaser and CanvasDataRenderer references from custom code. For charting, migrate to Sugar's native Charts plugin or bundle an alternative charting library within your customization package.

Deprecated Functions and Methods

The following functions and methods carry @deprecated annotations and are scheduled for removal in a future release. They were deprecated prior to 26.1 and continue to function in 26.1 but should be migrated.

Superglobal sanitization helpers — include/utils.php. In-code message: "Superglobal sanitizing will be completely abandoned. Use the new InputValidation service instead."

General utility functions — include/utils.php:

Database audit methods — include/database/DBManager.php. The audit API is moving from the DB layer to SugarBean:

Deprecated REST endpoint actions:

Data Changes

Email Denormalization Upgrade Script

A new upgrade script upgrade/scripts/post/9_DenormalizeEmailsFields.php runs on upgrade and adds four columns to emails_email_addr_rel, backfilled from the emails table:

• date_sent (datetime)
• team_set_id (id)
• state (varchar(100))
• assigned_user_id (id)

A new index idx_eearl_email_sent is also created on [email_address_id, deleted, team_set_id, date_sent DESC, email_id].

Note: On instances with large archived email volumes, the UPDATE ... JOIN backfill and index creation can take 10–45+ minutes and hold row-level locks. A mid-run failure leaves partially denormalized data. Pre-upgrade recommendation for large instances: run the Prune Database scheduler job to completion before upgrading to reduce email table size.

New Indexes and Vardef Changes

• New int field job_run_order (default 1) added to the Schedulers module. A Repair/Rebuild is required post-upgrade.
• DynamicFields.default_value type changed from varchar(255) to text. Any custom code that reads default_value and enforces a 255-character maximum must be updated — the field is now unbounded.
• Documents.name.sort_on changed from name to document_name.
• validateModel: true added to the Assign, Claim, and Close action button definitions in the Cases module vardefs.
• template_supported => true added to the Dashboards and Reports module metadata.

Platform Updates

Logic Hook Resilience — Exception Handling

Both static and instance hook invocations in include/utils/LogicHook.php are now wrapped in individual try-catch blocks. SugarApiExceptionInvalidParameter exceptions are re-thrown (correct for API validation contexts); all other Throwable errors are caught, logged as fatal, and surfaced as a system notification to admins via a new saveNotification() method. A static cache ensures at most one notification per user-module pair per session. A failing custom hook no longer crashes the entire bean operation.

Note: Custom hooks that previously failed silently will now emit a system notification. Monitor logs for "Error executing hook" entries. Hooks used in API contexts should throw SugarApiExceptionInvalidParameter to return proper HTTP 422 responses.

PDF Manager Logo Format Validation

PDF template header logos are now validated at save time. Supported formats: .jpg, .jpeg, .png, .gif, .bmp. Unsupported formats (.webp, .svg, .tiff, .tif, .heic) are rejected with HTTP 422 SugarApiExceptionInvalidParameter via the REST API, or an error message via the BWC UI.

Note: Convert all PDF template header logos to JPEG or PNG before upgrading. Update any integration that programmatically sets the header_logo field to validate format before submission.

PruneDatabase Scheduler Rewrite

The Prune Database scheduler job has been rewritten in src/Schedulers/Jobs/PruneDatabaseService.php with deadlock resilience (exponential backoff retry), audit table orphan cleanup, and per-table failure tracking across runs. See the Configurability Updates section for the new optional config keys.

Bug Fixes

• Fixed a fatal error that occurred during upgrade from 25.1.x to 25.2.0 (BR-13007).
• Fixed an issue where the 26.1 install wizard failed with a 500 error on MySQL (SUS-571).
• Fixed an issue where Sugar failed to load properly after upgrade on Windows (SUS-126).
• Fixed fatal errors on the Repair & Rebuild step during upgrade from 14.0.4 to 25.1.3 in multi-tenant setups (SUS-448).
• Fixed an issue where upgrading to 26.1.0 caused failures on instances with API customizations (SUS-548).
• Fixed an issue where the Show Changes feature in Opportunities returned a fatal error after upgrading to 25.2.0 (CSI 98647).
• Fixed an issue where sales stage and dropdown colors were lost after module install/uninstall on upgraded or cloned instances (CSI 98237).
• Fixed an issue where the upgrade script for the job_run_order field was incorrectly included; the script has been removed (SUS-476).
• Fixed an issue where Module Loader upload failed with "Could not find package file" when upload_dir was configured outside the Sugar root directory (CSI 99111).
• Fixed an issue where package installation failures occurred due to missing core classes related to PHP opcache corruption (CSI 98229).
• Fixed an issue where modifying an out-of-the-box dropdown caused the Package Scanner to fail installation of customizations exported via Studio (CSI 96552).
• Fixed an issue where the Package Builder and Deployer did not include all files when exporting custom subpanels (CSI 97739).
• Fixed an issue where the Cloud Insights link on the Administration page failed to load due to a CSP violation (CSI 98233).
• Fixed a PHP Fatal error: Uncaught Error: Class "Nonce" not found (BR-13243).
• Fixed fatal errors being hidden by Uncaught DomainException: The given security subject is not active (SI 89298).
• Fixed a Class "Module" Not Found fatal error when class_map.php contained a false entry for a custom module (CSI 98855).
• Fixed a PHP Fatal Error in ForecastMetricsApi.php during Forecast calculation caused by an array_merge type mismatch (CSI 98542).
• Fixed fatal errors in sugarcrm.log when switching between tabs in Forecasts (SUS-122).
• Fixed an issue where the Filter API returned an incorrect results count (BR-13041).
• Fixed an issue where the Filter API returned wrong record count, incorrect offset, and missing records in JSON results (CSI 95384).
• Fixed an issue where the FilterAPI response field order did not match the request body after field modifications (CSI 97467).
• Fixed an issue with the /Reports/:record/records endpoint in API version v11_25 (SUS-123).
• Fixed an issue where SugarACLActivities triggered a 500 error when the activity's parent bean was no longer accessible to the user (CSI 98342).
• Fixed an issue where a query failure in a report incorrectly returned a permission error message (CSI 95685).
• Fixed an issue where an improperly formatted date filter value threw an unhelpful server error on reports (CSI 94709).
• Fixed an issue where the Contains filter on Assigned To and other relationship fields forced a full selection, causing timeouts on list views and dashlets at high record volumes (CSI 98159).
• Fixed an issue where Global Search failed to index when a comment log entry exceeded 32,000 characters (CSI 97481).
• Fixed an issue where Global Search could exceed the maxClauseCount threshold when executing queries with multiple hyphen-separated tokens (CSI 97570).
• Fixed an issue where SugarBPM being an application hook forced execution order relative to module-level logic hooks (SI 83796).
• Fixed an issue where SugarBPM Send Message events after a Wait step did not respect User Locale, Language, or Timezone settings when field variables were included in a Process Email Template (SUS-9).
• Fixed an issue where a SugarBPM Receive Message Event was set to COMPLETED instead of CLOSED in pmse_bpm_flow, causing records to become stuck in a process (SI 82401).
• Fixed a PHP 500 fatal error in the SugarBPM validator when processing older process definitions (CSI 95495).
• Fixed an issue where Process Management failed to load or became progressively slower when hundreds of thousands of Process records existed (SI 89542).
• Fixed an issue where Quick Repair and Rebuild caused API-triggered BPM document generation via DocMerge to fail (CSI 96056).
• Fixed an issue where an HTTP 500 error occurred when saving a new Revenue Line Item with a custom field and a BPM Process Definition using Relationship Change Criteria (CSI 92792).
• Fixed an issue where hard-deleting data in pmse_inbox caused a process to retrigger again (CSI 93985).
• Fixed an issue where an Unauthorized Creation of Process Definition was possible when a user had Developer Access to at least one module (SUS-124).
• Fixed an issue where adding a column to a Case subpanel in Studio caused fatal errors in sugarcrm.log (SUS-152).
• Fixed a severe CPU spike and instance unresponsiveness triggered by a Studio configuration change (CSI 98411).
• Fixed an issue where fields could not be added to a subpanel layout if the layout had no existing fields (SI 86285).
• Fixed an issue where deleting a relationship left orphaned files in the Vardefs directory causing an Error: Invalid link (SI 89679).
• Fixed an issue where Dropdown Styles Extension files were not rebuilt during Quick Repair and Rebuild (CSI 95294).
• Fixed an issue where a missing Expression caused MetadataManager to fail, making the site inaccessible with a 500 error (SI 82950).
• Fixed an issue where invalid formulas could be saved in Studio, resulting in a crashed instance (SI 81905).
• Fixed an issue where Prune Database run on the 1st of the month orphaned audit records when parent records were deleted (SI 86770).
• Fixed an issue where OAuth 2.0 authentication with Exchange Online only sent one campaign email (CSI 98254).
• Fixed an issue where the Microsoft OAuth2 email authentication token expired after 90 days rather than refreshing (SUS-93).
• Fixed an issue where email accounts configured via Exchange Online did not allow users to send as other approved email addresses (BR-13300).
• Fixed an issue where the Email "From Name" was not being calculated correctly when sending via Microsoft Exchange (BR-13288).
• Fixed an issue where the Inbound Email Scheduler failed to archive all emails and prematurely removed them from the inbox (CSI 95509).
• Fixed an issue where the Inbound Email Scheduler logged a stat(): failed error in the job queue when downloading emails with attachments (SI 67377).
• Fixed fatal errors in sugarcrm.log during execution of the pollMonitoredInboxesForBouncedCampaignEmails and pollMonitoredInboxes scheduler jobs (SUS-251).
• Fixed fatal errors in sugarcrm.log during mail account setup (SUS-471).
• Fixed an issue where email_mailer_timelimit and email_mailer_timeout config options resulted in delays when sending a test email (CSI 92799).
• Fixed an issue where an imported email from a sender with a non-UTF-8 encoding caused the email record view to fail to load (CSI 95960).
• Fixed an issue where a DB500 error could occur in the Emails Subpanel and Timeline Dashlet when loading archived emails indirectly related to a contact (CSI 97607).
• Fixed an issue where sorting certain Emails subpanel columns caused a database error (CSI 98525).
• Fixed an issue where sorting columns in the Emails subpanel in Cases resulted in the error Error: Unknown field (CSI 98344).
• Fixed an issue where Report Grouping on a datetime field used UTC/GMT time instead of the user's timezone (CSI 96346).
• Fixed an issue where a report showed single-digit day/month dates when a UK/EU date format was set in the user profile (CSI 97195).
• Fixed an issue where a database error occurred on reports when sorting by deleted fields (CSI 95763).
• Fixed an issue where the SUM, MIN, MAX, and AVG summary options for the Duration Minutes field were missing in Summation Reports for Calls and Meetings (SI 79984).
• Fixed an issue where the Advanced Reports Custom Query builder returned a 404 instead of an invalid query screen (SI 86985).
• Fixed an issue where the incorrect export delimiter was used when exporting Advanced Reports to CSV (SI 77564).
• Fixed an issue where Report Chart did not sort based on the Display Summaries sort order (SI 80778).
• Fixed an issue where Advanced Reports could not be scheduled due to a CSP violation (BR-13388).
• Fixed an issue where Sugar Logic was not calculated until after Save for formulas using the relate function against Activities Flex relationships (SI 73566).
• Fixed an issue where formula validation of Calculation fields did not work properly (SI 77548).
• Fixed an issue where Assigned User fields were not evaluated properly by a Required if formula in another module (CSI 92022).
• Fixed an issue where a Required If formula containing a related link caused the Focus Drawer Record View Dashlet to break (CSI 92769).
• Fixed an issue where Listview Actions dropdown menu disappeared when certain Read Only If formulas were applied (CSI 92089).
• Fixed an issue where a dependent related formula did not display data in a subpanel (SI 80275).
• Fixed an issue where Sugar did not reconnect to the database after a query was killed by the Slow Query Killer or a timeout (BR-12110).
• Fixed an issue where Prune Database stalled on large tables (SI 80852).
• Fixed an issue where before_save hook changes were not audited (CSI 96102).
• Fixed a DB syntax error appearing in sugarcrm.log (BR-13260).
• Fixed an issue where PDF templates could not render images stored within the Sugar instance (BR-13091).
• Fixed an issue where editing a PDF template broke it (CSI 98492).
• Fixed an issue where TCPDF PDF templates no longer converted spaces in image file names (CSI 94322).
• Fixed an issue where DocMerge produced documents failed to open if a related() formula value contained the special symbol & (CSI 94295).
• Fixed login failures including erroneous STS Auth errors, unauthorized access, and return-to-login loops associated with Identity Management (CSI 95337).
• Fixed an issue where the Refresh Token in an IDM-enabled instance did not live longer than 24 hours (BR-13036).
• Fixed an issue where a regular user with external_auth_only = 1 did not appear in the Shared Calendar list (SI 89482).
• Fixed an issue where the FilterAPI incorrectly returned extra fields in the response even when the fields argument was specified (BR-13048).
• Fixed an issue where Group Users could not be deleted (CSI 95066).
• Fixed an issue where the LBL_SHOW_MORE label on Text Area fields could display "Show More Cases" instead of "Show More" (CSI 97216).
• Fixed an issue where currency field sorting triggered a DB error in custom modules with base_rate in the _cstm table after upgrading to 25.2 (CSI 98412).
• Fixed an issue where List View Count was inaccurate when filtering on multiple Tags for records related to multiple tags (SI 83020).
• Fixed an issue where the "Claim" Action Button did not respect "Required If" field validation (CSI 94987).
• Fixed an issue where PHP opcache corruption caused Call to undefined method fatal errors (SUS-315).
• Fixed an issue where regular users triggered redundant rebuilds after an admin QRR due to SystemProcessLock, causing server overload (SUS-304).
• Fixed an issue where the Scheduler UI displayed job run times in an unexpected timezone (BR-13130).
• Fixed an issue where the email "From" filter behavior was inconsistent when raw email addresses were used as primary addresses on records (CSI 91283).
• Fixed an issue where installing Sugar locally under certain offline conditions failed (CSI 97111).
• Fixed an issue where using the email_addresses_primary field in a template for a custom URL field resulted in a 500 error when opening any record in the module (SUS-288).
• Fixed an issue where the Sugar Market Integration used a deprecated API call (SE-9850).
• Fixed an issue where a "Page does not exist" error appeared when creating a new Case with an attachment (CSI 94268).
• Fixed an issue where the Emails subpanel used an inefficient search query, resulting in slow performance with large record counts (CSI 98123).
• Fixed an issue where an error occurred during MLP uninstallation (SUS-441).
• Fixed an issue where deleting relationships could break list views (SI 87737).
• Fixed an issue where the Product Catalog Dashlet displayed duplicated and inaccessible entries under specific Product Category and Template configurations (CSI 95867).

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, HTTP Headers (Referrer-Policy Header), SVG File Upload Sanitization, and BWC modules. We have also cleaned up and improved our logging messages around deprecations.

Note: Some of those security improvements were backported to Sugar 25.1.x.

Healthcheck Updates

• Built a healthcheck to detect and reclassify badVardefsMultienum issues from bucket MANUAL to bucket CUSTOM. The rule ID also changed from 526 (25.2.0) to 452 (26.1.0). Update any CI scripts or monitoring dashboards filtering on this rule's ID or bucket.