SugarCRM: Exceptions

A number of years ago I read a funny comment about computers which read as follows:

"The problem with computers is that they do what you tell them to do, not what you want them to do."

The point being that computers do not think, they just follow instructions. As such, programmers have to be mindful of the instructions given and anticipate problems. While it is not possible to account for every possible scenario that may generate a problem, we do want to accommodate common scenarios and capture problems as exceptions, allowing our code to fail gracefully and providing feedback to the user in the form of an error message.

Within the Sugar framework, it is possible to easily implement such exceptions and provide feedback to the user.

An exception class, named SugarApiException, is provided out-of-box and can be implemented into your PHP customizations as illustrated by the following pseudo-code:



For the above example, the Sugar API would return a response code of 422, with the body of the error message being the string defined in the code (i.e. 'You are missing a parameter required for properly invoking this endpoint.').

Of course, this would be more useful if we had a selection of response codes and errors. The list of available options is defined within the previously mentioned SugarApiException class, found in the following file:

./include/api/SugarApiException.php

Here is the definition for the example used in the pseudo-code, where you will see the response code and error title:

/**
 * One of the required parameters for the request is missing.
 */
class SugarApiExceptionMissingParameter extends SugarApiException
{
    public $httpCode = 422;
    public $errorLabel = 'missing_parameter';
    public $messageLabel = 'EXCEPTION_MISSING_PARAMTER';
}

Hopefully this will help save you time implementing a process for handling errors!

SugarCRM 101: Authentication

Did you know that Sugar supports 3 different mechanisms for authenticating a user upon them attempting to access the application? 

The authentication options are:

Sugar

LDAP

SAML

The Sugar option refers to the standard username/password combination an administrator can configure within Sugar, as described here:

https://support.sugarcrm.com/Documentation/Sugar_Versions/8.3/Ent/Administration_Guide/Users/#Regular_and_Admin_Users

If your organization maintains an LDAP capable server, such as Microsoft ActiveDirectory (AD), it is possible to utilize the AD user list to authenticate users attempting to access Sugar. Further details on configuring this option can be found here:

https://support.sugarcrm.com/Knowledge_Base/Password_Management/Configuring_LDAP_Authentication_Using_Active_Directory/

The third option, SAML, is similar in nature to LDAP in that the user list is maintained outside of Sugar, but access to Sugar can be obtained by providing a set of valid SAML credentials. Greater detail on using this option is given in this example:

https://support.sugarcrm.com/Knowledge_Base/Password_Management/Configuring_SSO_With_Okta/

These options provide a flexible authentication model for Sugar, but the options aren't mutually exclusive and their interaction can sometimes cause a bit of confusion.

For example, it is possible to configure a Sugar instance to use SAML and at the same time allow a user to access the instance by either providing SAML or standard Sugar credentials. It is also possible to configure Sugar such that the LDAP/SAML option is only applicable to certain users.

To alleviate some of that confusion, I have created the below flowchart to describe the process used by Sugar, taking into account the various authentication options that can be configured. 

Figure 1.1 - Authentication Process

I hope this helps answer some of your questions on authentication and Sugar.

SugarCRM DevOps: Compression

Question: Which would download faster, a 3.5 MB sized file or one approximately 500 KB in size?

It is not a trick question. Without a doubt, our expectation would be that the smaller sized file would download faster, regardless of the speed of our network connection to the server. But how can we reduce the size of payload if we cannot trim the actual contents? A quick and easy way to reduce the size would be to compress the content to be sent in the response.

If we apply this principle to Sugar, the compression of payloads sent from the web server to the browser would result in a snappier user experience, due to faster retrieval of data and other necessary components. As a general rule of thumb, we should always implement a compression methodology in order to help us achieve the best experience possible.

But how can one determine if compression is enabled and being utilized by the web server hosting a Sugar instance?

The image in Figure 1.1 helps us answer that question.

Figure 1.1: Example ListView response

To answer our question we must examine the web requests exchanged between our web browser and the web server. This can be easily accomplished within Chrome by accessing the Developer Tools and reviewing the contents of the Network tab, as illustrated in Figure 1.1.