Sugar Exchange Package Guidelines
The Sugar® platform is open and flexible. Developers can customize any feature or integrate any system with Sugar using a Sugar Module Loadable Package. This flexibility requires guidelines so that SugarExchange customers can rest assured that all package offerings adhere to consistent quality standards and will not interfere with existing customizations or prevent software upgrades.
This guide outlines the minimum standards we expect from any Sugar Developer writing code for the Sugar platform. From the development of Sugar packages to security, user interface, encapsulation, and performance considerations, SugarCRM takes the safety and integrity of the Sugar application and its community very seriously. Compliance with these guidelines is a requirement for any package installed into Sugar's cloud service. Failure to follow these guidelines is grounds for having your package removed from Sugar's cloud service and de-listed from SugarExchange.
SugarCRM reserves the right to change these guidelines at any time. Please send any questions or feedback on these guidelines to firstname.lastname@example.org.
These best practice guidelines have been curated based on years of collective experience working with Sugar Packages that get used by Sugar customers every day.
Use a consistent coding style
Invest in unit testing during development
We recommend running unit tests frequently during the development process. We suggest developers run tests before each commit and as part of an automated continuous integration process. Running tests often means you catch failures sooner which makes them easier and cheaper to fix.
Use Sugar REST APIs
The easiest way to integrate with a Sugar instance is not to install anything into Sugar at all. For Sugar 7, we have a full client REST API that is used to drive our web interface, our mobile client, and our plug-ins. If you can do it from our user interface, you can use our REST API separately to do it as well. If the REST API doesn't do everything you need it to do, it is very easily extensible. You can easily write code that adds your custom API endpoints in a minimally invasive way.
Use Module Builder when possible
Many integrations can be accomplished with the help of Module Builder and the Sugar REST API. Module Builder allows you to quickly design new modules for Sugar that match concepts that you want to add to a Sugar instance. These custom modules can then be installed and populated via the REST API, making it a powerful integration mechanism that doesn't require writing a line of Sugar code. Using custom modules will prevent conflicts with other customizations, as well. For more information, please refer to the Module Builder documentation.
Use Extension framework and Dashlets for Sugar code customizations
The Extension framework is the way to add server-side changes to a Sugar instance in a loosely coupled way. Dashlets are the best way to add new, custom user interface components to a Sugar instance that gives users maximum flexibility in how they use your app. These mechanisms also avoid conflicts with other customizations since Extensions are additive and do not replace core files.
Protecting and controlling access to CRM data is of paramount importance. It is important that Sugar Packages are good stewards of CRM data and access control.
Use TLS/SSL for web services calls
Just as we don't recommend running Sugar in production without TLS/SSL, all web-services calls that are initiated from a Sugar Package should also use SSL. The concern is the exposure of user credentials, OAuth/session tokens, or sensitive CRM data via plaintext transmission that would otherwise be handled securely.
Do not hardcode sensitive information
You also should not hardcode any credentials, API keys, tokens, etc, within a Sugar Package. Sugar Packages and Sugar application code is never encrypted so there is always a risk that an attacker could discover these things and abuse them. Usernames and passwords, OAuth tokens, and similar credentials for accessing 3rd party systems should be stored in the database (for example, on the config table). The Sugar platform also provides encryption utilities that allow information to be stored in an encrypted form. These settings could then be changeable by the Administrator via the Administration panel or some other end-user input.
User Interface Guidelines
Sugar packages can be used to add new user interface components or front-end customizations to Sugar. It is important to consider the impact that these changes have on the user experience and the look and feel of the Sugar application.
Use the Sugar 7 Styleguide
In Sugar 7, we have doubled down on our emphasis on creating the best possible user experience. While other applications may use different usage patterns than the ones used in Sugar 7, it is important to think about how new functionality or integrations that you build in Sugar 7 fits within the overall Sugar 7 user experience. Users do not tolerate an inconsistent experience within a given tool - it makes it harder to learn to use, which lowers adoption of Sugar as well as your application.
We want to make it easier for you to build applications within Sugar that use a consistent theme and user experience patterns, so we have included a styleguide for the Sugar application. You can find a link to the styleguide from the Sugar Administration page. There you can find all the information you need to leverage Sugar 7's styling including our CSS framework.
Don't use incompatible UI frameworks or external CSS libraries
Mixing outside user interface frameworks into the Sugar application via a Sugar Package can easily break many different parts of the application. Please only include as much CSS as you need and make sure that it is properly formed so that it doesn't affect other parts of the Sugar application. At the very least, using different frameworks or themes within your application will create a disjointed experience for the end user. While your package may be installed into Sugar, the user experience will not be seamless.
An important aspect of the quality of a Sugar Package is how well encapsulated and loosely coupled it is. A well encapsulated and loosely coupled package will encounter the fewest issues during upgrades, fewer breakages due to core code changes or due to interactions with other installed packages, as well minimizing bugs or problems that end users encounter.
Use Extensions framework and Custom Modules as much as possible
A well-encapsulated package prefers the use of Custom Modules over customizing and repurposing existing Sugar Modules. A loosely coupled package uses Extensions framework for customizing and connecting with the core Sugar application. Only override the behavior of core Sugar application files as a last resort.
Avoid customizations to core Sugar application files
Developers are strongly discouraged from overriding core Sugar Modules or Sugar framework code. In many cases, a cleaner approach for accomplishing the same goal exists. For example, using a logic hook to extend the behavior of a SugarBean instead of overriding the SugarBean itself. Every core customization is a barrier to successful upgrades that creates recurring development costs over time. This is exacerbated in heavily customized Sugar instances as other customizations may exist on these files. Anytime there is a conflict then manual intervention by a Sugar Developer is required which is not only inconvenient but costly for everyone involved. If you do make core Sugar customizations then keeping track of such changes is very important to get in front of potential conflicts with other packages and upgrades.
Use Package Scanner to ensure your Sugar Package is ready for SugarCloud
Sugar Packages should be designed with Sugar's cloud service in mind, as many Sugar customers choose this hosting option over hosting on-site or through a Sugar partner. Code that gets loaded into Sugar's cloud service must pass the Package Scanner utility and must not adversely impact the SugarCRM infrastructure. This stipulation is outlined in the SugarCloud Policy Guide. Package Scanner can be enabled on any Sugar instance via the Sugar Administration panel which allows this to be tested easily. You should also educate yourself in some alternatives to blacklisted functions.
Sugar is primarily a database application however with the introduction of Sugar 7, more and more business logic is executed within the user's web browser. It is best to avoid pre-optimization and use tools to properly identify the root causes of performance issues that users could encounter.
Index for large frequently used queries
The most common performance bottleneck for Sugar is the database. Using slow query logging makes it possible to identify bottlenecks and correct them. One way to address query bottlenecks is to extend vardefs to add indices during package install to improve the performance of those queries.
Add scheduled jobs to prune large database tables
If your Package adds database tables that can tend to grow very large over time, it is a best practice to include scheduled jobs in your package that can be used to prune the size of this database over time. For Sugar, these background tasks can be created and managed using the Job Queue framework. At the very least, you'll want to create a Custom Job that Sugar Administrators can then run as needed. This will allow the package to remain in tip-top shape for your users over time. Especially if they are running on Sugar's cloud service because direct access to the underlying SQL database to do manual tuning and cleanup is not permitted.
Ensure your application does not block user interface during long running processes
If your application prevents the user from getting feedback or using the interface while it is running a long process, this will impact the perceived performance of the application. Users typically expect some UI feedback within half a second. If you have transactions that will take longer than that, it is best to use the Job Queue framework to defer them for later or move them into a scheduled Custom Job.
Last modified: 2021-02-17 02:44:13