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!

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!

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.

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

Villains hate 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!

Do you need to set up your Sugar development environment but only have 20 minutes to spare?  With the help of Vagrant, I’ve got you covered. Check out my new video below:

Prefer text-based instructions?  Get them here.

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 set.

Also 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.

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).

• Sugar 7.10 Developer Release Notes
• Sugar 7.10 Unit Tests (Requires Dev Tools sign-up for access)
• Sugar 7.10 Developer Guide that includes an updated Migration Guide
• Sugar 7.10 Developer Webinar Recording

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!

Have you ever found yourself wishing you could create a custom Sidecar user interface within your Sugar instance? Maybe you want to allow users to visit a URL that displays a custom view.

It turns out that creating a linkable URL (or route) to within the Sugar client is fairly simple. In this post, I’ll walk you through how to implement a new route in your Sugar instance that displays an alert.

What is a Route?

Sidecar utilizes the Backbone Router as the method for controlling client-side navigation within the Sugar application. The Router will take the current URL in the browser (the route) and call the appropriate callback function.  The callback could do something like display an alert or load a Sidecar Layout or View.  The Router will pass information included in the route like a module name and a record identifier to the callback function.

Most of the routes are already set up for you. For example, visiting a Sugar instance URL that ends with “#Home” will load the default dashboard layout. Visiting a URL that ends with “#Accounts/<id>” will load the Account record view for the record with the appropriate identifier.

Creating your own route

When you decide to create your own route, the first thing you’ll want to do is decide what your custom route should be. In this example, we’ll use “helloWorld” as our custom route, meaning that the full URL will be http://yourSugarInstance/#helloWorld.

Next, you need to decide what should happen when someone accesses the route. Let’s display an alert message that says, “Hello, fabulous person!”

Now that we know what we want to do, it’s time to code!

Create a new file in your Sugar directory:  ./custom/javascript/customRoutes.js:

SUGAR.App.events.on("router:init", function(){
    //Register the route #helloWorld
    SUGAR.App.router.route("helloWorld", "Hello World", function() {
        SUGAR.App.alert.show('message-id', {
            level: 'info',
            messages: 'Hello, fabulous person!',
            autoClose: false
        });
    });
})

This code registers the custom “helloWorld” route during the “router:init” event.  This code could exist in a file with any name at any location.

The next thing we need to do is create a JSGrouping extension that will tell Sugar we have created custom routes.

Create a new file in your Sugar directory: ./custom/Extension/application/Ext/JSGroupings/myCustomRoutes.php:

<?php

foreach ($js_groupings as $key => $groupings) {
    $target = current(array_values($groupings));

    //if the target grouping is found
    if ($target == 'include/javascript/sugar_grp7.min.js') {
        //append the custom JavaScript file
        $js_groupings[$key]['custom/javascript/customRoutes.js'] = 'include/javascript/sugar_grp7.min.js';
    }

}

Before we can try our custom route, we need to run Quick Repair.  Login to Sugar as an administrative user and navigate to Administration > Repair > Quick Repair and Rebuild.

Now we’re ready to test.  Navigate to http://yourSugarInstance/#helloWorld.  Unless you missed a step, the alert you created will appear!

Note:  you may need to refresh the page once to pull in the updated JavaScript in order for the alert to appear. It’s a good idea to disable your browser cache when doing JavaScript development too.

If you want to take things a step further and display an iframe for a custom route as seen in the screenshot below, check out the Canvas IFrame Building Block example.

For more detailed information on creating custom routes including how to designate new route patterns, see the Developer Guide.

Are you ready to build an integration with Sugar but not sure where to start?  You’ve come to the right place!

When you want to access or interact with information stored in Sugar, the REST API is a great place to start.  In this tutorial, you’ll learn how to authenticate to the Sugar REST API.  Then you’ll learn how to perform create, read, update, and delete (aka CRUD) operations.

Watch the video tutorial below or view the text-based tutorial at bit.ly/tutorial_rest.

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!

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

Please visit this post at the Developer Blog’s new home if you want to leave comments.

https://community.sugarcrm.com/community/developer/blog/2017/11/29/a-new-sugar-ux-coming-in-winter-18

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.

Style comparison between current Sidecar (left) and new Sugar UX (right).

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.

RESTful APIs have always been a big part of the Sugar application, as well as the most appropriate touchpoint for integrating with other enterprise systems. Unfortunately, for a long time they weren’t tested especially appropriately. Traditionally, REST APIs at Sugar were tested with PHPUnit, but only on the classes themselves – they weren’t actually tested via direct use of HTTP. Worse, the tests were messy – they often assumed existing data was present, and when it wasn’t, it was created and not deleted afterwards.

Thorn was envisioned as a solution to this problem. It’s intended to test Sugar’s RESTful API directly, abstract away unhelpful boilerplate, leave your database clean, and let you test like a user.

Thorn was open-sourced earlier this year after a brief internal testing period and is now available for any Sugar developer to use from github.com/sugarcrm/thorn. It is open source and available under the Apache License, version 2.0.

This initial post will focus on a technical and philosophical overview of Thorn. For usage information, see the Thorn website.

Key design elements of Thorn tests

Thorn has a few key design principles that informed how it was developed and how we test with it.

Test like Goldilocks

If all you’re trying to prove with a test is that a REST API works, an end-to-end test with Selenium (or similar) is too expensive and too likely to fail for unrelated reasons to justify running it. Unit tests aren’t particularly helpful either; most API bindings don’t carry around all that much interesting functionality since they’re mostly proxies to other code that do the real work.

Thorn is thus meant to test an API as an API, by using real HTTP requests and real data. The result is nimbler tests that nevertheless accurately reflect how Sugar’s APIs are actually used.

Thorn does this by building on top of the excellent Chakram framework – an extension to the well-known Mocha test runner that makes it easy to make HTTP requests from within tests and make assertions about their responses.

In other words, Thorn is just right for testing REST APIs. (Cue groans from the readers.)

Take nothing but responses, leave nothing but logs

Tests that make implicit assumptions about the system under test have a number of issues. They can’t be safely parallelized or run in isolation, because they might be assuming that one of the other tests in the suite provides that data.

Furthermore, a test you can only run once is a useless test, because if it fails, you may have to wipe out your entire environment and start over just to make one single code change. If the test fails again, this will get frustrating very quickly.

Thorn’s Fixtures API provides the solution. Fixtures.create lets you decide what records should exist in the database before your test begins, and Fixtures.link can be used to create relationships between them. You only have to give values to fields you really care about – anything else necessary will be transparently filled in by Thorn. Finally, Fixtures.cleanup cleans up whatever mess in the database your fixtures made.

Another nice side effect is that a good Thorn test can run on any compatible Sugar instance – even an anonymized customer instance, in the case of partners or system integrators.

Think of a good Thorn test like a backpacking trip. You have to bring everything you need with you, so pack light and only bring what you need. And don’t ruin the trail for the next camper to come through – clean up after your data.

Be the user

The only reason an API should exist is so a front-end (or a different service’s back-end) can talk to it. But either way, ultimately APIs exist because some user felt it would be helpful for a service to do something. To that end, a good Thorn test is written with the users of the API (reflecting real usage by end users in real roles) in mind.

Mocha’s traditional behavior-driven-development interface helps here, but Thorn’s main advantage is the UserAgent interface. With Agent.as, you can specify exactly what user you want to perform an action as, then use Chakram’s convenience methods (get, post, etc.) to perform exactly the same action that a Sugar user would do.

Your users expect your API to be honest. So when you’re writing a Thorn test, keep that in mind and keep them honest.

Remember your passwords

Authentication, session expiration, and re-authentication are some of the thorniest (pun intended) issues you’ll experience while working with APIs.

Thorn provides solutions to all of these problems, with an aim of limiting manual developer intervention and undesired nondeterminism whenever possible. Authentication is performed implicitly by Thorn for each user involved in a test; there’s no explicit login required.

Furthermore, if a user’s request fails mid-flight for authentication reasons, the request is automatically retried and the test proceeds as normal.

You wouldn’t want a user to have to login every time they go to another page of your app and Thorn doesn’t expect that of you either.

Cool, how do I stop RESTing and start testing?

For now, check out the Thorn website. In a later post, I’ll go into greater depth about good Thorn testing practices and show how you can test a sample REST API endpoint.

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!

TLDR

Developing Sugar on Docker, get up to speed now!

The long version

What are Docker containers?

If containers for you are more than the two pictures below… then you are in the right place!

As you might be aware, there has been and there continues to be a lot of hype around containers. The hype really started with Docker, but containers have been around for a while (more or less), in a different shape or form. If you are not yet familiar with containers or are confused about the difference between a virtual machine and a container, this blog post from Docker might be useful to you.

Personally, I was deploying container-based virtualised single purpose hosting environments (now labelled micro-services?) for my customers, back when it was not so trendy. It was about 10 years ago when I was leveraging OpenVZ. OpenVZ is slightly different (eg: it has state/persistent storage for every container), but in the end you can run multiple lightweight containers that share the custom linux kernel of their host.

What Docker has managed to do differently is make infrastructure deployments repeatable and portable. An application can be shipped together with its Docker container directives, providing the same exact configuration across different host environments. The infrastructure looks more like code, which simplifies the process of automating and delivering software deployments. Teams using Docker found that the lines between development and operations blurred even further, and guess what? DevOps was born!

Docker has made it easy to get up and running with a technology for development purposes. A developer just needs Docker installed on his or her local machine (or on a linux VM) and a “Dockerfile”, to get an application up and running. If he or she needs to replace a single component of the infrastructure for testing purposes, they simply swap a few directives and re-build. The same application is executing on top of a slightly different platform. How awesome and easy is that?

With the always increasing pace of software development innovation required today, and with applications becoming more and more decoupled from each other (and at the same time integrated), the deployment velocity needs to keep up as well to be able to quickly deliver innovation across the board on a multitude of heterogeneous backends.

This need for a fast deployment velocity can be fulfilled with the aid of flexible containers and orchestration technologies when their delivery is seamlessly baked into the traditional software development pipeline. Obviously containers are not the silver bullet or the answer to every known question, but they are currently applicable to a vast set of different workloads and use cases.

Docker in production

At this stage, I do not have direct experience with Docker in production environments, but, as with any technology, there is always someone willing to share their horror stories…

Jokes aside; with the increase in popularity of orchestration, the extensive backing and support from various cloud providers and how lightweight it is, I am convinced Docker is the way to go for micro-services deployment and orchestration in production environments as well. As a matter of fact, container-technology adoption is constantly growing across the board and not just for micro-services.

Sugar on Docker

Enough said about the containers topic. Here it is, my attempt at creating a set of development stacks for Sugar with Docker.

I have to thank one of our long-standing partners Cédric Mourizard from Synolia for the initial work (read more in his previous blog post). The Sugar Docker setup has been polished here and there over the past 6 months, and it is now to a point where I only run Sugar locally with this solution.

I highly encourage you to give it a try. Have a look at how Docker can fit in your development process, and, if it does not yet fit into it, think about how it could help you streamline your overall software delivery pace and capabilities.

Flavours used

Let’s give a quick overview of the various components used. When using *nix I’m a Debian kind of guy. So that’s that.

LAMP stack, Elasticsearch and Redis on top of Debian.

Stack components

It might evolve over time, but for now the main containers are:

• Apache load balancer – Load balances requests between the cluster of Apache PHP web servers, round robin
• Apache PHP web server – Web server(s)
• MySQL database – Database
• Elasticsearch – Sugar search engine
• Redis – Two purposes: Sugar object caching service and PHP Session storage/sharing service
• Cron – Sugar background scheduler processing. Note that this is enabled immediately and it will run cron.php as soon as the file is available, and it will attempt to do so every 60 seconds since its last run
• Permission – Sets Sugar instance permissions correctly and then terminates

The application files are shared on the “cluster” (if you can call it that) through a directory based mounted volume to offer persistent storage. We also have various persistent storage directories within ./data/ for all the other software components that need them.

Based on the selected stack (within the ./stack/ directory) you will be able to pick and choose the various versions of the stack components available, and to decide if you want a load balancer and multiple web servers or just a single web server during initial development phases. Because the Docker containers are stateless, it is possible to run the same Sugar installation (stored on the persistent volume) either with PHP 7.1 or PHP 5.6 and swap between versions within seconds.

Current software versions

Currently, there are a few stack combinations available that run the supported platform for Sugar 7.9.

Containers are available with PHP 7.1/5.6, MySQL 5.7, Elasticsearch 1.7.5 and the latest Redis. When selecting a stack, it is possible to run it as a single web server or as two web servers behind a load balancer.

Sugar 7.10 is not available for on-site hosting but it can be downloaded for local development, so, I have prepared a single stack leveraging PHP 7.1, compatible with the required matching platform. The main difference in stack requirements between Sugar 7.10 and earlier versions is the Elasticsearch version 5.4 requirement. Elasticsearch 5.4 seems to be more memory hungry, so be prepared for that.

Finally there is an additional stack for 7.9 upgrades, running both Elasticsearch 1.7.5 and 5.4, to allow future testing of upgrades to the Sugar Spring ’18 release.

Getting up and running

Most of the details you require to get up and running are within the README.md of the git repository. In terms of where to run this setup, you have the option of leveraging docker-machine or to run your own VM, as currently the native Docker for Mac does not perform well with the mounted volumes for persistent storage.

I personally use a Debian VirtualBox VM on a Macbook. If you want to run the same VM as I do, I have prepared a VirtualBox appliance export. You can find the appliance on this repository, as well as more details on how to deploy it on your Mac. It runs a NFS share as well, so that you can mount the directory locally and code with your preferred editor.

During my process, I’ve tried also Vagrant to help with automatic deployment of the VM instead of building an appliance, but I did not obtain the same performance footprint (not even close). So I abandoned that route long ago.

Now you are up to speed with Sugar on Docker, and you might have realised how containers can help your business gain velocity.

Feel free to let us know your thoughts, by leaving some comments below!