Skip navigation
All Places > Developer > Blog > Authors Matt Marum
1 2 3 4 Previous Next

Developer

111 Posts authored by: Matt Marum Employee

While we introduced PHP 7.1 support in the Sugar 7.9.0 release back in May 2017, we have up until now continued to support PHP 5.6. But PHP 5’s days are numbered. We will be dropping support for PHP 5.6 in the Sugar 8 and Spring ‘18 releases. Sugar 8.0.0 and Spring ‘18 will only support PHP 7.1. Long live PHP 7!

 

In the Sugar cloud, we have been migrating from PHP 5.6 to PHP 7.1. With this transition, we have discovered some additional PHP 7 pitfalls that we want to make sure everyone avoids in their Sugar customizations. These problems affect any version of Sugar that uses PHP 7. They are both centered around a new ArgumentCountError that was introduced in PHP 7.1.

 

If you haven’t already, you should check out the old blog post we did on preparing customizations for PHP 7. There are lots of benefits for using PHP 7 with Sugar. Not only are there performance improvements but Sugar code as well as customizations are now able to take advantage of more advanced PHP language features.

 

Let’s take a look at the two pitfalls we want to help you avoid.

 

Do not use deprecated PHP 4 style constructors in Logic Hooks classes

You should not be using PHP 4 style constructors in PHP 7 at all, but there is an additional complication that is introduced when you are using Logic Hooks with PHP 7.1.

 

Take the following example:

 

class Hook {
    public function hook($bean, $event, $arguments)
    {

    }
}

 

The issue here is rooted in the fact that functions and classes in PHP are case insensitive.  The hook() function contained within the Hook class is interpreted as a PHP 4 style constructor even though the names differ in case.

 

For logic hook code where the class name and function name differ only in case, it would cause Sugar to throw fatal PHP errors in PHP 7.1 and warnings in earlier PHP versions. Since the class name and function name does not match in the example, Sugar will not recognize hook() as a constructor. So Sugar will first instantiate the Hook object and then subsequently call the hook() function later. But PHP recognizes hook() as a constructor. So PHP would instantiate a Hook object without passing the needed arguments to hook(). Calling a function with an incorrect number of arguments in PHP 7.x throws a fatal ArgumentCountError.

 

When using PHP 5 with Sugar, this would generate a PHP warning and ultimately the hook() function would be called twice; once with no arguments for the constructor and then a second time with arguments to process the hook.

 

So there’s all kinds of things going wrong here in this very brief example.

 

For compatibility reasons, we have fixed this case sensitive behavior where we will only call this function once in Sugar 8.0.0 but even then you are still using a deprecated PHP 4 constructor in PHP 7. This is either unintentional or simply a bad idea.

 

You must use function names that are different than your class names in your Logic Hook classes.

 

We can easily fix the example above by changing the function name.

 

class Hook {
    public function afterSave($bean, $event, $arguments)
    {

    }
}

 

 

Do not define too many arguments for Logic Hooks functions

Now we should take a look at another issue that will throw an ArgumentCountError.

 

class Hook {
    public function afterSave($bean, $event, $arguments, $customArgs)
    {

    }
}

 

The developer who wrote the afterSave() function above may have been trying to save time by adding the $customArgs argument to a standard after_save module logic hook function to handle some alternative usages. The issue is that Sugar is going to call this logic hook function with three arguments instead of four, which will throw an ArgumentCountError in PHP 7.1. In PHP 5, a warning is simply logged and the function is still executed.

 

It should go without saying that functions should be called with the correct number of arguments.

 

¯\_(ツ)_/¯

 

We can fix the example above to ensure that functions can always be called with the correct number of arguments.

 

class Hook {

    public function afterSave($bean, $event, $arguments)
    {
        $this->otherSave($bean, $event, $arguments, array());
    }

    public function otherSave($bean, $event, $arguments, $customArgs)
    {

    }

}

 

You must ensure that your Logic Hook functions use the correct number of arguments.

 

For most logic hook events that is three arguments but sometimes it is two! Check the event definitions in the Logic Hooks section of the Developer Guide if you aren’t sure how many arguments are required!

 

Recap

Let’s recap what you should do to prepare your Logic Hooks for PHP 7.1:

  • Ensure that none of your Logic Hook classes contain functions have the same name as the class. Remember that PHP is case insensitive when it comes to class and function names.
  • Ensure that your Logic Hook functions use the correct number of arguments.

Hi there, Sugar Developers!

 

We want to make sure your customizations and integrations are ready for the Sugar 8 and Spring ‘18 releases, so we’re hosting two webinars just for you!

 

Webinar Topics

We’ll discuss the big changes that are likely to impact you including the following:

  • Review Data privacy features used for GDPR compliance (if you’re not thinking about this, you probably should be!)
  • New Sidecar components and features that support Data Privacy
  • New Admin panel to register custom API platforms
  • Changes to Audit APIs, data model, and behavior
  • Changes to supported platforms and libraries
  • Update on the Professor M School

 

Webinar Information:

We are holding 2 sessions to accommodate various geographical locations. Please choose ONE of the following times below.

Monday, April 23nd 6:00 PM - 7:00 PM PT

OR

Tuesday, April 24rd 8:00 AM - 9:00 AM PT

(Choose one)

 

Register Here


We will be posting the webinar recordings here in the Developer space for those who are unable to attend the live sessions.

Please don’t hate me. It’s not really my fault. I am sorry to say that every single Sugar developer needs to care about the General Data Protection Regulation (GDPR) and data privacy in general. It is a sign of the times and part of the interrelationship of technology and modern society that impacts the software we implement today and in the future.

 

I can explain but first let me provide some context.

 

What is the General Data Protection Regulation (GDPR)?

 

First off, I am not a lawyer or a GDPR specialist. If you really want to understand what GDPR is and what steps you need to take to be compliant, then I suggest reading the Regulation for yourself or hiring counsel. GDPR is a complex set of rules, and there’s still a lot of debate about what it all really means. Other interpretations, including yours, may be different from what I describe below.

 

Many of our colleagues in the European Union are well acquainted with the GDPR which requires full compliance by May 25th, 2018. But for those of you who do not live in the European Union (EU), I highly recommend reading Data Privacy and GDPR in Sugar by Deepak Deolalikar. It covers some GDPR basics as well as provides an overview of some of the features planned in Sugar to help our customers comply with GDPR.

 

In short, the spirit of GDPR is about allowing individuals (data subjects) to have control over their own personal information. GDPR ensures that personal information or Personally Identifiable Information (PII) of EU citizens are processed responsibly. EU citizens have a right to privacy that in many cases means you must comply with their requests to access, restrict the use of, or delete the personal information that is stored about them.

 

The scope is broad and the penalties are severe. Any organization that stores personal information about EU citizens, even if that organization is based outside the EU such as in the United States, is subject to this regulation.

Penalties for failure to comply with these regulations could result in fines that start at €20 Million or 4% of total revenue if that value is greater.

 

Are you paying attention now?

 

Data Privacy is yet another software globalization requirement

 

When we build software, we make sure that it meets all sorts of requirements. We design for performance, scalability, and security. We work hard to ensure a positive user experience and high quality software. At SugarCRM, we also focus on making sure that all our products are ready for the global marketplace. That means that over the years we have invested in translations into dozens of languages and support for multiple currencies, numerous date and time formats, right-to-left languages, Unicode character encodings (though we’re still working on emojis), and 508 compliance.

 

The fact is that GDPR is just one example of a data privacy regulation at a time when there are dozens more government bodies all over the world considering and implementing new data privacy regulations. UTF-8 character encoding and a translatable UI are no longer enough to make sure your software is ready for the global marketplace! The responsible collection and processing of personal information is now an additional obligation for all software developers.

 

With the upcoming Sugar Spring ‘18 (cloud) and 8.0.0 (on premise) release, we are now investing in data privacy features. These features will help provide our customers with the tools they need to comply with GDPR and many other data privacy rules or regulations.

 

These data privacy features and other data privacy concerns will impact Sugar customizations and integrations that collect or process personally identifiable information (PII).

 

Future installments on Data Privacy and GDPR

 

We will be exploring several data privacy topics in the coming weeks. Here is a quick summary.

 

Collecting explicit consent before storing data in Sugar

 

GDPR has strict requirements for consent. Unless you have an existing lawful basis for using personal information, you need to collect positive and unambiguous consent from the data subject even before data is stored in Sugar. For example, a web to lead form with a pre-selected opt-in checkbox is not going to cut it in the EU. We will be exploring ways to make sure you are collecting explicit consent using techniques like double opt-in (DOI) or confirmed opt-in (COI).

 

Managing PII data and the right to erasure in Sugar

 

There are new Sugar APIs being added for working with PII as well as features that allow Sugar customers to comply with data subject requests like the right to access their own data and the right to erasure. In particular, external systems that integrate with Sugar may need to identify and implement their own erasure measures in compliance with a data subject request.

 

Improved change log and attribution of changes using Data Sources

 

We are implementing some enhancements in Sugar’s change log functionality to allow for finer grain tracking and proper attribution for changes to PII. We will be exploring these platform level enhancements including the ability to define new data sources (for example, an integration) that are responsible for changes to data.

 

What do you think?

 

What are some of your biggest data privacy or GDPR concerns? Let us know and we’ll try to address them in future posts.

 

Also, please follow this space and this blog to be sure you are notified when the next installment is posted!

What is the Sugar Metadata API?

As you probably know, Sugar metadata encompasses the settings, data model (Vardefs), and visual layouts (Viewdefs) used by the Sugar application. The majority of changes made to Sugar using Sugar Studio, Module Builder, or even custom code are implemented by modifying metadata.

 

How can I know that the custom field or custom modules that you need for your integration to work exists in Sugar?

How can I know what are the allowed values are valid for a Sugar dropdown field?

How can I know if a field is required?

How can I know the display label for a given field?

How can I know what fields are available in Sugar that I can map back to an external data source?

 

The answers to all these questions and many more can be found in Sugar metadata.

 

On the server side, metadata is implemented as an extensible set of PHP associative arrays. But how does this information get sent out to Sugar clients like your web browser, mobile app, or even the Outlook plug-in? This is accomplished via the Sugar metadata endpoint of the Sugar REST API.

 

GET /rest/v11/metadata HTTP/1.1
Host: localhost:8080
OAuth-Token: ...
Content-Type: application/json

 

The full metadata response comes back as a very large JSON object. It's usually a few megabytes in size (about 3MB in a stock version of Sugar Winter '18) but can be much larger depending on customizations. Make sure compression is enabled on your web server if you are going to be using it over a slow connection!

 

 

The value to using the Metadata API is that you can discover changes in Sugar configuration and Sugar customizations. New custom fields, relationships, modules, changes to Sugar views and layouts, and much more are all represented in Sugar metadata responses.

 

From a REST API perspective, the only way to accurately know the current data model for any given Sugar instance is to use the Metadata API.

 

Since the Metadata API is so important, here are three important tips to keep in mind to make development easier.

 

Tip 1: Retrieve only what you need

Metadata API calls can generate a huge response depending on your Sugar instance configuration and the customizations that may exist. You should specify filters on your metadata request in order to narrow the response to the data that you actually need. Narrowing what is returned will improve performance on both server side in terms of generating the response but also on the client side where you need to parse the JSON response.

 

For example, if you are integrating with only the Accounts module then you may only need to concern yourself with that part of the metadata. Specify a type_filter and module_filter as URL parameters to only return module metadata for the Accounts module. Other supported type_filter options are server_info, config, relationships, labels, languages, currencies, views, layouts, full_module_list, and etc.

 

GET /rest/v11/metadata?type_filter=modules&module_filter=Accounts HTTP/1.1
Host: localhost:8080
OAuth-Token: ...
Content-Type: application/json

 

Tip 2: Cache metadata, update only when it changes

You can safely cache the metadata that you need if you keep track of the _hash value returned in the metadata response.

 

You should present that hash value in the X-Metadata-Hash header on subsequent Sugar REST API requests to ANY endpoint. If the metadata hash is out of date then Sugar will return a 412 PRECONDITION FAILED HTTP response. You should then retrieve updated metadata from the Metadata API and store the updated metadata hash value.

 

GET /sugar/rest/v11/Accounts HTTP/1.1
Host: localhost:8080
OAuth-Token: ...
Content-Type: application/json
X-Metadata-Hash: 705fb99230e2ec60b59f481c6831a7cf

 

Also worth mentioning, many of our API resources (such as records and our metadata) implement HTTP caching. If an API response contains an E-Tag HTTP header then you can safely cache the response body as well as the E-Tag value. If you present this value in the If-None-Match HTTP header properly on a subsequent HTTP GET request for that resource, you will get an empty 304 NOT MODIFIED response back if it is safe to continue using the cached version of the previous response. This is another approach to reduce needless processing.

 

GET /rest/v11/metadata?type_filter=modules&module_filter=Accounts HTTP/1.1
Host: localhost:8080
OAuth-Token: ...
Content-Type: application/json
If-None-Match: 705fb99230e2ec60b59f481c6831a7cf

 

This allows you to update your local copy of the metadata as soon as it changes and precisely no more often than that.

 

Tip 3: Different users and platforms will retrieve different responses

If a user is assigned a role that doesn't have access to a particular module then the metadata for that module will not be returned when that user accesses the metadata API. Makes sense, right? 

 

Sugar also support things like role based views which will provide alternative UI layout metadata based upon the current user's role.

 

Different platforms will have different metadata responses as well. The mobile platform retrieves module metadata that reflects the needs of our Sugar Mobile app. Mobile UI components look a lot different from what you see when you access Sugar from your browser. The metadata that is retrieved is significantly different to accommodate these changes.

 

For example, the mobile client uses separate edit and detail views for representing records instead of a single record view like you find in Sugar web client. This is represented in the mobile metadata response.

 

What is the Input Validation Framework?

The Input Validation Framework is a centralized security framework used to validate that external input is provided in the expected format. Validating user input is critical because it is the basis for generated HTML and REST API output, used in the construction of SQL queries, used to access files, etc. Malicious input can be used to compromise the security of a Sugar instance and the underlying infrastructure. The validation framework provides better control than the pre-existing input sanitization techniques applied to user input within Sugar.

 

Fixing Input Validation problems

Sugar’s input validation was enabled but only logging failures as warnings into the sugarcrm.log file since the 7.7.1 release. With the Winter ‘18 release, the validation.soft_fail configuration setting will now default to false. This means that input validation checks will be strictly enforced by default instead of simply logging warning messages.

 

For more information about using validation constraints in your own custom code, check out the Sugar Developer Guide, the previous UnCon Security presentation, or the Winter '18 webinar.

 

Identifying input validation violations

Beginning in the Winter ‘18 release, input validation violations are reported as PHP Fatal errors in the PHP error log and Critical error messages in sugarcrm.log file. Invalid requests will generally be terminated with an HTTP 500 error as well.

 

Let’s walk through an example of an input validation violation.

 

In this example, we have a customization that is accessing the Sugar instance at the following URL: sugarcrm/ult/#bwc/index.php?module=xxxxx.

 

If xxxxx is not a registered module, there will be a FATAL error in the PHP error log.

For example,

[15-Jan-2018 22:04:09] WARNING: [pool www] child 1940 said into stderr: "NOTICE: PHP message: PHP Fatal error:  Uncaught exception 'Sugarcrm\Sugarcrm\Security\InputValidation\Exception\ViolationException' with message 'Violation for REQUEST -> module' in /srv/www/<instance>/prebuild/test/ult/sugarcrm/src/Security/InputValidation/Request.php:280"
[15-Jan-2018 22:04:09] WARNING: [pool www] child 1940 said into stderr: "Stack trace:"
[15-Jan-2018 22:04:09] WARNING: [pool www] child 1940 said into stderr: "#0 /srv/www/<instance>/prebuild/test/ult/sugarcrm/src/Security/InputValidation/Request.php(209): Sugarcrm\Sugarcrm\Security\InputValidation\Request->handleViolations('REQUEST', 'module')"...

 

The sugarcrm.log will also show an error.

For example,

Tue Jan 16 06:05:18 2018 [1941][-none-][CRITICAL] InputValidation: [REQUEST] module -> Invalid module xxxxx

 

From the end user perspective, these fatal errors will cause pages to appear blank or stalled during loading. If you inspect the browser console when this happens, you will likely see HTTP errors logged.

 

Fixing input validation violations

The steps to take to fix the violation are going to depend on the exact constraint that you are violating. Luckily the exceptions you find in the PHP error log and the messages in the sugarcrm.log will indicate the constraint that you are violating.

 

In the above example, attempting to access a BWC view for an unregistered custom module “xxxxx” is causing the failure. If you make sure that the module you are using is properly registered in Sugar’s module list, or modify your request to use an existing Sugar module, then this will fix this issue since the constraint is checking if the module name is a known modules installed in this Sugar instance.

 

There are basic Symfony framework PHP constraints that we use. These do not need an in depth explanation. The basic Symfony constraints can be used to validate URLs, date time formats, etc. Check out the Symfony documentation for these basic constraints.

 

In Sugar's implementation, we add our own set of validation constraints. These constraints extend from Symfony's Constraint and ConstraintValidator classes and are located in the ./src/Security/Validator/Constraints directory of your Sugar installation. Each Constraint is enforced using a related Validator class. You can inspect the Validator classes to see the precise logic that needs to be followed. For example, the Bean/ModuleName constraint is implemented by the Bean/ModuleNameValidator class. This constraint is used to ensure that the input is a string that matches the name of a valid module with an associated SugarBean class.

 

One of the basic rules that most of these constraints implement is that an input type should be a scalar. This means we expect most user input to be integer, decimal, string, or boolean values.

 

Sugar Constraints

The list provided below may not be exhaustive.

  • Bean/ModuleName
    • Must be a string. The Module’s SugarBean class must be retrievable using BeanFactory. For example, this is used in legacy Workflow.
  • ComponentName
    • Must start with a letter and may only consist of letters, numbers, hyphens and underscores. For example, this is used throughout Studio and Module Builder for module names, package names, and Sugar Logic functions.
  • Delimited
    • By default, must be comma delimited scalar values. For example, this is used in conjunction with other constraints.
  • DropdownList
    • Dropdown lists must only consist of letters, numbers and underscores. For example, this is applied to dropdown lists during module install.
  • File
    • File must exist in an allowed file path and must not include null characters or any directory traversals. For example, this is used by FileLoader utility class.
  • Guid
    • Must be a string with alphanumeric or dash characters. For example, this is used with SugarMVC Views.
  • InputParameters
    • General input validation for GET, POST, REQUEST superglobals. Must be scalar values and strings should not contain null characters.
  • JSON
    • Must be a string that is JSON decodable. Returns decoded PHP associative array. For example, used in Configure Navigation Bar Quick Create.
  • Language
    • Must be a locale code that matches an installed language. For example, this is applied where languages can be selected in UI.
  • LegacyCleanString
    • Reimplements input sanitization rules previously used with clean_string() function.
  • Mvc/ModuleName
    • Must be a string. A more permissive test than Bean/ModuleName that allows any module name that can be found in global module lists. For example, this is used throughout SugarMVC Views.
  • PhpSerialized
    • Must be a PHP serialized string that does not contain objects. Returns unserialized value.
  • Platform
    • Must be a string that is under 128 characters and contains alphanumeric and dash characters. Must be a known Platform value such as “base”, “mobile”, “portal”, etc., or one registered using Platform extension. For example, this is used to validate REST API login requests.
  • Sql/OrderBy
    • Must be a string that represents a valid ORDER BY SQL clause. For example, this is used in SugarMVC list views.
  • Sql/OrderDirection
    • Must be a string that is uses SQL keywords “ASC” or “DESC”. For example, this is used in SugarMVC list views.
  • SugarLogic/FunctionName
    • Must be a string that only uses word characters and dashes. For example, this is used in Sugar Studio.

 

If you encounter a failure, then you should be able to identify the constraint that you are violating from your error logs. By looking at log messages that appear immediately before the failure, and possibly some exploration in the Sugar user interface, you will be able to identify the failing request. From there, you can use the information above to alter the request to comply with the necessary constraints.

 

This is not a substitute for Sugar field level validation!

An important thing to note about the Input Validation Framework is that it is not the only input validation mechanism available. For example, there is still separate field level validation that occurs when users create or edit records. Sidecar customizations or Studio configuration can still be used to perform validation of user provided input for each field of a record in a user friendly way. For example, Sugar will let you save a record without filling out required fields and will display a user friendly warning that tells user what to correct. The Input Validation Framework is centered around security and does not provide the same usability than you would get validating user input using Sidecar or Studio settings.

The Sugar Winter '18 release is fast approaching! Hopefully you are as excited about the new Sugar UX as I am!

 

As usual, Lauren Schaefer and I will be hosting a developer webinar to help get you and your customers prepared for the new Winter '18 (7.11) release. Please read below to learn more about the agenda and do not forget to register! We run these webinars twice, so no matter where you are in the world, we hope that one of these times will be convenient for you.

 

Winter '18 Technical Webinar Agenda

 

Technical Training AgendaWebinar Times
  1. Impacts of new interface
  2. Sugar Exemplar app (more below)
  3. Restricted REST API platforms (more below)
  4. Removal of some LESS files
  5. Emails subpanel changes
  6. Input Validation Framework (now the default)

Monday, January 22nd 4-5:00 PM PT
Tuesday, January 23rd 8-9:00 AM PT

Register Here

 

We will be posting the webinar recordings and deck to the Partner Portal for those who are unable to attend the live sessions.

 

Sneak peak of Sugar Exemplar app


The new Sugar Exemplar app is designed to demonstrate best practices for developing Sugar customizations (think DevOps and QA!) and a solid example of what upgrade-safe customizations should look like. We’ll tell you more about the app and how you can get involved during the webinar!

 

Reminder about restricted REST API Platforms


ISVs and developers who use a platform string to connect to a Sugar instance will need to update their existing API integrations. For more information - please refer to this blog post on how to to proceed.

 

Get on our developer mailing list!

 

Remember to opt-in for Sugar Developer communications to make sure you don't miss this and other important updates.

Sugar v11 REST API

In order to support some cool new dashboard features, we made some enhancements to our Dashboard APIs in the Fall '17 release. So we added a new REST API version, v11, in that release in order to ensure clients and integrations that were using the existing v10 Dashboard APIs would continue to work properly. For more details on the v11 API, we recommend you check out a recording of our recent Fall '17 release developer webinar and the related migration guide.

 

Today we won't focus on version 11 specifically but instead on how the Sugar platform will be handling REST API versioning in the future. So read on!

Passing API version using HTTP Header

For REST v10 and our older web services frameworks, the API version was specified exclusively via the URL.

 

Example 1)

 

GET <sugar>/rest/v10/me

 

In the Fall '17 (7.10) release, we introduced an additional way to specify the API version: using an HTTP header. This change allows resource URLs to be treated as unique identifiers to resources regardless of the API version in use.

 

The REST API version can now be specified via HTTP Accept header. The REST API version should be specified in either the URL or in the HTTP Accept header but not in both locations at once. This new method of specifying the API version in the HTTP Accept header better adheres to RESTful architectural principles. By essentially encapsulating the API version as part of media type, a single resource at a given URL could offer multiple representations using different data formats and API versions.

 

Example 2)

 

GET <sugar>/rest/me
...
Accept: application/vnd.sugarcrm.core+json; version=42

 

We recommend that client start specifying the API version in the Accept header instead of as a component of the URL. Sugar clients will adopt use of the Accept header in the future.

Future use of semantic versioning in REST API

As you probably have noticed, the REST API version is a property of the Sugar REST API as a whole and not individual endpoints.

 

We plan to implement a semantic versioning policy with MAJOR.MINOR format for the REST API next year.

 

The version will be specified in the request Accept header as MAJOR.MINOR (ex. 11.1) whereas the version in the endpoint url will be specified as MAJOR_MINOR (ex. 11_1).

 

The Sugar REST API MAJOR version will be incremented for each Sugar release where compatibility is being broken on any endpoint. The Sugar REST API MINOR version will be incremented for each Sugar release where an API endpoint is changed or additional API endpoints are being added without breaking compatibility.

 

Not every new Sugar release will result in new REST API versions. Our intent is to only add new features or make breaking changes to our REST API only when it is not possible or prudent (ex. for performance reasons) to do so with the current API.

 

When there is a breaking change, older API versions should continue to work as-is. For example, if a parameter was removed in newer version, the old version should still support that parameter.

What are breaking and non-breaking changes?

We want to be clear about what we consider to be an API breaking change and what is not.

Breaking Changes

  • Removing or renaming an endpoint, a request parameter, or a fixed response field
    • For example, removing the GET /rest/v10/<module> endpoint or renaming the _acl field to _access_control.
  • Removing support for a HTTP request method on an endpoint
    • For example, changing from PUT to PATCH method for updating records.
  • Change in type for a request parameter
    • For example, a change from an Integer to Decimal value.
  • Change in response field format
    • For example, a change in encoding for a response field from plaintext to base64.
  • Semantic changes to request parameters
    • For example, a change from treating the % symbol as a literal instead of as a wildcard or a change in default value.
  • Semantic changes to an API endpoint
    • For example, an endpoint that was documented to return all records by default and now returns no records by default.

Non-breaking Changes

  • Metadata related changes in behavior
    • For example, when Sugar metadata (Vardefs, Viewdefs, etc.) changes are introduced during a Sugar release or as a result of a customization then REST API responses can vary as a result.
  • Adding a new endpoint
    • For example, adding a GET rest/Accounts/:id/map endpoint.
  • Adding a parameter to a request
    • For example, adding a boolean parameter called shorten_text that decides if long text fields are shortened to 200 characters.
  • Adding a field to a response
    • For example, adding a _self field with link to resource URI in GET responses.
  • Adding support for another HTTP request method
    • For example, adding support for PATCH method to an endpoint.

 

If you ever encounter a situation where there is a breaking change on a particular API version between future Sugar releases, then please report those issues via the Sugar Support portal.

Deprecation process for old API versions

Old REST API versions will continue to be supported until at least one year after they have been deprecated. We want to exercise good judgement on how quickly we remove old API versions but please understand that SugarCRM cannot indefinitely support an unlimited number of REST API versions.

What should you do?

  1. When building new Sugar clients or integrations or updating existing ones, adopt the latest available REST API version possible in order to take advantage of all the latest features.
  2. Use the HTTP Accept header to specify REST API version when using Sugar Fall '17 release or later.
  3. Monitor the release notes and documentation on each new Sugar release for deprecation notices on old API versions. Keep our customers safe by planning ahead!

SugarCRM is on a mission to empower our users to delight their customers. To that end, we are pleased to introduce the first phase of visual restyling, and give some tips on how to work with the new UX.

Our process in developing the new UX

Sugar 7 introduced the Sidecar framework with massive user interface improvements (called SugarUX) and a modernized architecture. Since then, we have been working hard on the next iteration of SugarUX built on the Sidecar framework. Our guiding principles came from our customers and their feedback on Sidecar. A competitive analysis and feedback from customers revealed three concerns; cluttered complicated UX, inefficient unguided layout, and a drab outdated user interface.

 

The SugarCRM User Experience team (led by Brian Ng) launched a rigorous heuristic evaluation of the web and mobile Sugar products. Issues were identified as we evaluated key use cases and new solutions were documented. This thorough understanding of the product, customers, and the industry has helped us identify which issues to address first.

 

Dark gray text on light gray background led to poor legibility. Heavy blacks and gray linen added to the dated look and feel.

Sugar Mobile had a dark and drab visual design. Buttons for key actions were positioned differently on key screens.

 

Establishing Goals

With an understanding of the problems, we set goals for ourselves.

  • Improve design for over 100 usability issues, prioritized by impact to the user's ability to get their job done.
  • Establish a clean and modern visual design language, with rules documented in a style guide.
  • Ensuring our products are accessible by all, meeting Web Content Accessibility Guidelines (WCAG) compliancy.

 

Guiding Principles for our new Design

We established three design principles: Clear, Consistent and Efficient. These principles guided all of our decision making. Establishing principles helped to resolve differences of opinions and to focus on user frustrations.We determined what colors and fonts would positively affect our use cases and still reflect our brand.

 

 

We have adopted Open Sans as the Sugar UX base font. It’s an open source font optimized for web and mobile interfaces with text heavy layouts. It’s known for its open, neutral type shape and friendly appearance. For colors, we have selected a color palette that is friendlier, modern and brighter.

 

We also selected a set of colors and fonts that would positively affect our use cases and still reflect the SugarCRM brand. Finally, we tested concepts in the real world, with real users in key flows to observe how they played out in practice.

 


 

Mobile has a bright appearance and color placed in strategic locations to help users identify groups of information.

 

Results

  • First revealed at SugarCon to over 1000 attendees where customers gave feedback.
  • A new visual design language, documented in a Style Guide (coming soon), empowering customers and partners to implement SugarUX consistently on our product.
  • Launch of the new SugarUX on our Sugar Mobile apps, available already on the the Apple App Store and Google Play.

 

 

Coming in Winter ‘18!

 

The first phase of our new UX is coming in Winter '18 release and we want to make sure the Sugar Developer community is first to give it a test drive. If you have built any Sidecar components or customizations (Dashlets, custom views or layouts, etc.) then you should verify that they display properly in new UX. As with all code level customizations, it is up to Sugar developers to make sure that you fix your code so that your customizations display properly in the new UX.

 

From implementation perspective, these changes have been made entirely in CSS where we've adjusted the styling for existing CSS classes. So, areas of concern would be in places where you have overridden the styling for Sugar's core CSS classes or have introduced your own CSS through the use of ./custom/themes/custom.less. The majority of customizations that simply use our existing CSS classes are expected to adopt new styling without errors.

 

As usual, we will be running an invitation only technical Preview program for the Winter '18 (On-Demand only) release. If you want to make sure that your organization is considered for this preview then please e-mail developers@sugarcrm.com and mention your interest in test driving the new Sugar UX!

 

Building your new Skin test plan

We have referred to this effort as the “new skin” because this first phase primarily involves changes to CSS and no significant changes to default HTML structure for any of our Sidecar Components.

 

How do you make sure your customizations are still pixel perfect? What follows below are some tips for you and your team to build a test plan.

 

Exploratory Testing

We recommend devoting a fixed amount of time to doing some exploratory testing in order to make sure your customizations look great in the new skin. How much time? It depends on how much UI you have. For example, it should not take you longer than a few minutes to test a custom Dashlet and uncover any bugs that you may want to address.

 

Guidelines for Testers

If you are testing, what are you looking for? Here are some tips.

  • Customizations only. Testing should focus on customizations that your team created.
  • CSS overrides. If you use a ./custom/themes/custom.less file or include your own CSS files, then you’ll need to pay special attention to these changes since they will likely need to be updated.
  • Scrolling. Are you able to scroll and are there things that are inaccessible even with scrolling?
  • Ellipsifying. When you shrink the window size down or reduce the available space for data on custom list views, record views, etc, do they ellipsify and show tooltips on hover?
  • Responsiveness. Resizing the browser window or switching to and from responsive-mode. Observe what happens to elements on page.
  • Orientation on tablets. Alternating display orientation between landscape and portrait modes.
  • Toggle things. Open/close drawers, menus, edit and detail mode on record views, etc.
  • Settings. Change system and profile settings that may alter how things look like date/time format, currency, etc.

 

Comparisons with out of the box Sugar

This post includes some example screenshots of what the new skin looks like out of the box. Comparing your customizations to the out of the box look and feel will help you identify things that you may need to change in your customizations. We encourage testers to keep two windows open while testing to compare the out of the box behavior in one window with your customizations in another window more easily.

In Sugar 8 / Spring '18, Sugar administrators can now configure API platforms using the Administration panel. The Platform extension is still available if you want to register a custom API platform as part of a Module Loadable Package.

Sugar uses platforms to support the needs of multiple Sugar clients.  The Sugar REST API uses the platform parameter to indicate which platform is being used.  If you’d like a refresher on what the platform parameter is and how to use it, check out this blog post.  In Sugar 7.9, we added a new Platform extension that we advised developers to start using in the Sugar 7.9 Migration Guide.  The Platform extension allows you to indicate a particular custom platform should be allowed when the disable_unknown_platforms configuration setting is on.

 

Changes coming in Winter '18 release

In the Winter '18 release, we will be preventing REST API access to Sugar from unknown platform types. Sugar has a configuration setting disable_unknown_platforms that controls whether or not unregistered platforms are allowed to be used when logging in using the REST API. The current default value for disable_unknown_platforms is false. In the Winter '18 release, we will be changing the default to true, which is how it is already reflected in the documentation. If your integration uses a custom platform, this custom platform will need to be registered in each Sugar instance or your integration will break!

 

How do I know if I'm affected? New

In order to avoid conflicting with end-user sessions, some REST API integrations specify a different “platform” during login. Developers have often employed this technique to prevent integrations from interrupting or conflicting with active end-user sessions.

 

Below is an example of a login request that uses a custom platform:

 

POST /rest/v10/oauth2/token
{
  "grant_type":"password",
  "client_id":"sugar",
  "client_secret":"",
  "username":"{{username}}",
  "password":"{{password}}",
  "platform":"<SOME VALUE>"
}

 

Registering a new platform for an integration

 

Integrations must register any custom platforms they plan to use. For compatibility with Sugar On-Demand, we recommend creating a Module Loadable package that includes a simple Platform extension.

 

./custom/Extension/application/Ext/Platforms/<integration name>.php

<?php

/*

* A valid platform name requires:

* - Max length of 127 characters

* - Valid characters are: a-z, A-Z, 0-9 - (hypen) _ (underscore)

*/


$platforms[] = '<integration platform name>';

We recognize that is a change in assumption since it involves an installation of a package where previously no package had to be installed at all. We are working on an alternative approach as we roll out additional Identity Management (IdM) functionality that would allow for more convenient configuration of integrations.

 

Example Module Loadable Package

An example module loadable package has been added to the UnCon github repository. This package can be used as a template for those needing help understanding how to construct a package that will enable their API integration.

 

https://github.com/sugarcrm/uncon/tree/2017/custom-platform

Sugar Fall '17 (7.10) is now available!

 

You've heard all about this, but I'll recap. SugarCRM's fall 2017 release is a Sugar On-Demand only release. This is the first release that follows our new Sugar release process. Our on-premise customers will get a roll up spring release that includes features from this fall and subsequent winter release. So all of our customers will enjoy all of the same advanced features--just not all at once.

 

Here are some of the great developer resources available for the Sugar Fall '17 release (also known as Sugar 7.10).

 

Last, but not least, we will be providing developer downloads of On-Demand releases such as 7.10 that can be used by Sugar developers for code development and test purposes.

 

On-Demand Developer Builds

 

Sugar Developers have long relied on local development environments to prepare their Sugar customizations and integrations regardless of whether a particular customer was running in Sugar On-Demand or On-Site. Use of modern IDEs and debuggers as well as file system access all require running Sugar code outside of the On-Demand environment.

 

As we plan to evolve our On-Demand environment to support more development use cases, we have made a pragmatic decision to allow authorized SugarCRM Customers and Partners to download On-Demand Developer Builds via the Sugar Community.

 

Access to this space is restricted to users who have Download Software permission associated with their Sugar Community account. Check out the On-Boarding Sugar Developers guide to learn more about how to make sure that developers within your organization are registered and have appropriate permissions to access the Developer Builds space. Note that it currently can take up to 24 hours for the permission to access the Developer Builds space to update once permission is granted.

 

We are providing source code downloads as a courtesy and on an "AS IS" basis for the sole purposes of development and quality assurance. Production use of Sugar 7.10 code outside of Sugar On-Demand is unsupported and will not be tolerated. Please review the terms of use in the OD Developer Builds space for more details on restrictions.

 

Keep up to date with Sugar Developer News!

 

Did you miss the recent Sugar Fall '17 Release developer webinar? If you were there, you would have learned all about the Developer Builds space sooner. So, don't miss the next one! Sign up for Sugar Developer News today!

In our most recent set of security releases, we made some changes in Sugar that address input sanitization issues reported by a 3rd party security researcher. Conveniently, these issues can be addressed with the input validation and CSRF form authentication frameworks added in Sugar 7.7.0.0 and 7.7.1.0. Both of these frameworks offer "soft" failure modes that will log warnings into the sugarcrm.log instead of fatal exceptions.

 

Input Sanitization Soft Failures

CSRF form authentication is strictly enforced by default. But, up until now, the default for the input validation framework has been to use soft failure mode. Choosing to make soft failure mode the default was a pragmatic decision to maximize compatibility for Sugar customizations while developers updated customizations and integrations. However, these recent reported vulnerabilities make it clear that it is time to take the next step to more strictly enforce input sanitization. SugarCRM plans to strictly enforce input validation in upcoming releases. We will also remove the soft failure mode options at that time which will break customizations or integrations that have not adopted CSRF form authentication or pass that do not pass input validation.

 

Strict enforcement of Input Validation and CSRF Form Authentication

You should enable strict enforcement of the Input Validation and CSRF Form Authentication checks now for two reasons: (1) to ensure that your Sugar customizations and integrations work properly after upgrading to our winter releases and (2) to create the most secure environment for your current users. The configuration settings in question are the Input Validation 'validation.soft_fail' flag as well as the CSRF 'csrf.soft_fail_form' flag.Sugar Cloud has disabled soft failure modes by default but for Sugar On-Site you can adjust these settings for yourself. Add the following lines to your config_override.php file.

$sugar_config['validation']['soft_fail'] = false;
$sugar_config['csrf']['soft_fail_form'] = false;

 

Strictly enforced checks

In response to security issues, there are now strictly enforced input validation checks that ignore the validation.soft_fail configuration setting. In particular, we added strict validation to the platform authentication parameter used in our REST API. This can have an impact on platform identifiers using characters that are not part of the POSIX portable filename character setAlso recall the disable_unknown_platforms configuration setting affects the use of platforms. Custom platforms should be registered using the Platforms extension. This check is planned to be enforced in Sugar On-Demand in the future as well.

 

What you need to do to prepare customizations

In development instances,Set validation.soft_fail setting to false. Set disable_unknown_platforms setting to true. Then run regression tests on your integrations and customizations to very they still work.In production instances, Enable warn log level to collect and analyze any input validation or platform name violation warnings.

 

Other Resources

Slides from the UnCon 2016 session on Sugar's input validation framework are also available in the Sugar Community. More information about best practices for using the Platform parameter can also be found on a previous post on this blog.

Greg Khanlarov, Director of Mobile Development, is so excited about the launch of the new Sugar Mobile SDK that he is speechless!

 

 

If you are coming to SugarCon, make sure you get your hot hands on the new Sugar Mobile SDK first! On Tuesday, you can join Greg for his presentation Sugar Mobile SDK deep dive. Next Wednesday, at the UnCon Tutorials by the Experts, you can meet Greg and other folks from our Mobile development team and learn how to build your first custom Sugar Mobile app.

 

Read on for more details on the Sugar Mobile SDK!Are you building mobile CRM apps from scratch?  Is your team stuck deciding between Hybrid vs. Native?  Maybe you’re trying to deliver a premium mobile experience, but you don’t have the budget or skills. STOP.  Take a deep breath and consider what we’ve spent the past two years building.Sugar Mobile SDK - the first Mobile CRM SDK that favors convention over configuration.  Start with a proven mobile application in use by tens of thousands of users today, and add the pieces that are unique to your business.  Focus on creating value for users instead of uncertainty and risk.

 

What is Mobile SDK?

Mobile SDK enables developers to extend Sugar Mobile functionality beyond what is possible through studio configuration.  Common examples are:

  1. Custom fields, dashlets, views, buttons
  2. Support for mobile device management
  3. Styling, theming, navigation
  4. Native device capability integration (GPS, camera, etc.)

Extending Sugar Mobile using the SDK results in a custom mobile application that the author is responsible for building, maintaining and distributing.  Upgrade-safety and strong API contracts have been designed into the SDK to reduce the risk of upgrades breaking extension functionality.  Developers should be familiar with:

  1. Sidecar and Sugar customization
  2. Mobile application development with javascript
  3. iOS and Android application publishing processes

A custom mobile app is a mobile app developed on top of the Mobile SDK. Specific configuration and branding makes a given mobile app custom. Additionally, a custom mobile app may contain custom business logic developed in JavaScript, HTML, and CSS.

 

How do I get access?

You can get access directly from the Mobile Tools Portal. The portal is restricted to partners and customers running Enterprise and above. If you are having problems with access, check out the On-Boarding new Sugar Developers guide in the Sugar Community.

 

What are the benefits of the Mobile SDK?

The Mobile SDK’s formalized APIs and guidelines will help you extend SugarCRM Mobile in an upgrade-safe manner. Sugar has done the heavy lifting by allowing you to extend the SugarCRM Mobile app that will speed up your development so you do not need to build your own application from scratch.  Developers will also benefit from new features added on ensuing upgrades of the SDK.

 

What does the SDK allow you to do?

CustomizationExamples
Custom MenusAbility to add custom main menu items Ability to add custom right menu items
Custom field types Enable field validation Custom fields such as signature fields
Custom ActionsGeolocation for checkin-checkoutLaunch another app (e.g. Skype)Barcode/QR scanningOverride file actions
Custom DashletsAdd custom actions Build custom Dashlets External Source DashletFiltered List DashletRecord Summary dashletStatistics Dashlet
Custom ViewsBuild custom to-do listsModify table formattingExtend the detail viewExtend the opportunities list view
Native Plug-insThe SDK already supports standard native capabilities such as geolocation and camera access.  In the event you need to add other native capabilities, there is a way to do this.

 

How do I get help or provide feedback?

All development questions should be directed to the Mobile Developers community. If you need to file a defect or enhancement request, please submit a case to our support team.

You have may have seen a recent video where a menacing figure was growling about Quotes customizations and a "Professor M."

 


 

 

 

Who is Professor M? Well me technically. But let me share with you the story.

 

The School for Gifted Coders

 

Coming to SugarCon? Great! You are part of the inaugural class of Professor Marum's School for Gifted Coders. You can leave your No. 2 pencils at home, but you should bring your laptop.

 

The fact is this school is just getting started and since we're a not-for-profit it also means that budgets are tight! But we've got a secret weapon. Can you guess what it is? Sugar of course!

 

We plan to use Sugar to attract student applicants and process applications. We plan to use it to manage our relationships with current and former students. We will also use it to track and forecast donations and contributions to the school to keep it all running.Let me cut to the chase. We have a head start but if you can help us get our CRM system up and running then you will all get an "A+" and that 4.0 GPA that you always wanted. Your parents will be so impressed.

 

 

So now you've got the backstory. Let's talk about what we want you to do before and during UnCon.

 

Installing the Professor M Scenario

 

Watch Lauren's video below for the step by step guide on how to install the Professor M scenario into your own local Sugar instance. If you do not normally run Sugar on your laptop then you might want to follow the Vagrant development environment guide first. Text-based instructions on how to install the Professor M scenario are available on GitHub.

 

 

Bring your laptop to UnCon Tutorials by the Experts

 

The Professor Marum story has been woven into each of the hands-on UnCon Tutorials by the Experts stations within Plaza A/B of the hotel at SugarCon. Each tutorial you finish will bring Professor Marum closer to the Sugar system of his dreams!

 

Who knows? If you pay close attention, you might find some more School for Gifted Coders shout-outs during the rest of SugarCon.

 

We've been having lots of fun with the Professor M scenario and we hope that you do too at SugarCon!

The SugarCRM team has embraced our theme for SugarCon this year (CRM Heroes) like never before! Check out these great videos from some of SugarCRM's best and brightest. You will meet all these heroes (and villains) at UnCon!  Register for SugarCon today!

 

Want to know who is this mysterious Quotes module engineer? You will have to come to find out!

 

 

More videos are below!

 

Meet Steven Parsley and Gabriel Rael from the Engineering team in Product group.

 

 

Meet Zac Sprackett our VP of Reliability and Release Engineering in Product group.

 

 

And last, but not least, you can also meet Olivier Nepomiachty from the Sugar Labs team!

 

 

You can find all these videos and more on our YouTube playlist and also in the UnCon space of the Sugar Community.

Here are a couple more UnCon promo videos from SugarCRM's remarkable technical teams.

 

First off, we have a video Nick Rose, an experienced solutions architect, and also the Director of Solutions Consulting in the Americas. Come to UnCon and check out Nick's session on the Understanding the Sugar Platform.

 

 

Next, we have the brilliant and humble Robert Gonzalez, Software Engineering Manager on the Product team. You can bet that his tutorial at UnCon will be truly remarkable!

 

 

Stay tuned for more videos from the UnCon team!Register for SugarCon today!