How platform parameter works in Sugar v10 REST API

Matthew Marum —  May 9, 2016 — 5 Comments

UPDATE July 24 2017

Sugar 7.9.0 introduced a Platform extension. This should be used for registering new platform identifiers for Sugar 7.9.0 and beyond.

What does the platform parameter mean in v10 REST API?

If you open your web browser’s network tools, a login request to the v10 REST API used in Sugar 7.6 will typically look something like the example below.

POST /rest/v10/oauth2/token HTTP/1.1
Host: localhost
Cache-Control: no-cache
Content-Type: application/json
{
     "grant_type": "password",
     "username": "admin",
     "password": "admin",
     "client_id": "sugar",
     "platform": "base",
     "client_secret": "",
     "current_language": "en_us",
     "client_info": {
         "current_language": "en_us"
     }
}

You can see in the request that we have specified a platform parameter called “base”. This parameter is optional (the default is base) so even if you have used the v10 REST API before you may not have been aware of it or what it means.

Sugar Platforms

Platforms are used by Sugar to support the needs of multiple Sugar clients.  For each client, you are allowed to specify unique Sidecar Viewdefs, custom or modified platform API endpoints, as well as the ability to support a concurrent user session.

Sugar platform specific code is found under the clients/ and modules/MODULE_NAME/clients directories.  Sidecar client metadata is implemented under clients/*/layouts|views|fields and platform API endpoints are implemented under clients/*/api.  Sugar will fall back to base platform implementation when a more specific implementation is not available.

In general, the Sugar v10 REST API will only allow a single session (specifically, a single OAuth access token) to be created for any single platform at any one time.  For example, you cannot log into Sugar from multiple different web browsers on different computers at the same time.  This is necessary to prevent users from sharing subscriptions while allowing users to simultaneously access Sugar using a mobile device and their browser.

This is allowed by the fact that the SugarCRM Mobile app uses the mobile platform identifier while the web client uses the base platform identifier.

The number of sessions that is allowed per Sugar Platform is controlled by the SugarOAuth2StoragePlatform class that is associated with with a particular platform.

For example, if you look at SugarOAuth2StorageBase.php, you will see that the base platform allows only 1 standard web session at a time.

However, examining SugarOAuth2StorageMobile.php will show that we allow 2 mobile sessions at a time to allow access from multiple personal devices such as smartphones and tablets.

Thus it is possible to change the number of allowed concurrent sessions by overriding or implementing a new a SugarOAuth2StoragePlatform class for a custom platform.

Specifying new custom platforms will generate new copies of metadata cache

Today, Sugar supports the ability to specify arbitrary platforms.  This allows you the ability to create your own custom Sidecar based clients that are configured with their own custom metadata that extends from the base Sugar metadata.

A side effect though is that Sugar will build a metadata cache for each and every platform that it comes across.  Even if no custom platform metadata is specified, it will just inherit from base metadata.

Problems caused by random platform IDs

Some developers have followed our previous advice in order to allow an integration to maintain concurrent user sessions by creating their own unique platform IDs.  However, in some cases we have found integrations using random platform IDs which causes a lot of bad side effects.

For example, generating new copies of platform metadata takes time, so there can be an impact on user interface responsiveness.  Disk usage starts to swell and the size of an instance back up grows tremendously. Also, downstream integrations and systems can be affected due to slowed API responsiveness because of all this extra processing.

Sugar 7.6 Changes

We have added a new Sugar Configuration setting called disable_unknown_platforms that is currently disabled by default.  SugarCRM will selectively enable this setting on Sugar On-Demand instances that appear to be negatively affected by use of random platform IDs.

You can enable this setting on your own instance by setting up a config override.

config_override.php

<?php
$sugar_config['disable_unknown_platforms'] = true;

When this setting is enabled then any custom platforms that are used must be registered via the custom directory.

custom/client/platforms.php

<?php
$platforms[] = 'base';
$platforms[] = 'mobile';
$platforms[] = 'portal';
// New one
$platforms[] = 'mine';

Changes in future Sugar versions

In the future, we plan to create an Extension for registering custom platforms. We also may enable this restriction more broadly in Sugar On-Demand. So it is important that Sugar Developers know how to properly use Sugar Platforms.

The Platform extension was added in Sugar 7.9.0.

Matthew Marum

Posts

Matt is the Director of Developer Advocacy for SugarCRM. Previously he was an Engineer on Sugar 7 and a Solutions Architect for the OEM program. He is also an avid trail runner, Boston Marathon qualifier and a karaoke aficionado.

5 responses to How platform parameter works in Sugar v10 REST API

  1. 

    Hi,
    I have used a custom platform parameter named “spectrum” and every thing is working fine but i have not entered any thing in “config_override.php” and “platforms.php”.

    Is the above mentioned entries are mandatory? my platforms.php looks like:
    $platforms[] = ‘base’;
    $platforms[] = ‘mobile’;
    $platforms[] = ‘portal’;

    and “config_override.php” looks like:
    <?php
    /***CONFIGURATOR***/
    $sugar_config['default_module_favicon'] = false;
    $sugar_config['show_download_tab'] = true;
    $sugar_config['enable_action_menu'] = true;
    $sugar_config['stack_trace_errors'] = false;
    $sugar_config['developerMode'] = false;
    $sugar_config['noPrivateTeamUpdate'] = false;
    $sugar_config['verify_client_ip'] = false;
    /***CONFIGURATOR***/.

    Please help.

    thanks in advance.

    Anup kumar

    • 

      Setting platform values in platforms.php is not mandatory today. Registering custom platforms may be mandatory in the future.

      • 

        Thanks a lot. It means, i can pass any value as platform in V10 rest Apis? without setting it somewhere?

        • 

          Please re-read the blog post and let me know if there’s something unclear. I thought I addressed this question above. There is a cost involved in doing what you describe.

Trackbacks and Pingbacks:

  1. Upcoming security changes to Sugar « Sugar Developer Blog – SugarCRM - October 11, 2017

    […] information about best practices for using the Platform parameter can also be found on a previous post on this […]

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s