Tutorial:  How to register custom platforms in Sugar instances via Platform extension

Beginning in the Winter ‘18 release, Sugar is enforcing a rule that all custom platforms must be registered in each Sugar instance where the custom platform is used.  In this tutorial, we’ll work step-by-step through the process of checking to see if your integration uses custom platforms, creating the fix, installing the fix, and testing the fix.

Before you begin

Before you begin, you’ll need a copy of Sugar. Check out the On-Boarding new Sugar Developers guide if you are not sure where to go to get access to Sugar code.

Next, you’ll need to install PHP on your local machine if you haven’t already.

You’ll also need a local environment that can run Sugar so that you can test your fix.  The fastest and easiest way to get your environment setup is to use one of the Vagrant boxes we provide.

Finally, you’ll want to set up Sugar.  Navigate to your running copy of Sugar (http://localhost:8080/sugar/ if you are using one of our Vagrant boxes) and work through the installation wizard.  Note the username and password you select for the administrator.  Also, be sure to select the option to install the demo data as we will use it when we test our fix.

Identify your custom platforms

The first thing we need to do is identify the custom platform(s) your integration uses.  Some of you may already know what your custom platforms are.  If not, you’ll need to inspect your integration code and look for REST API calls that authenticate to Sugar.  They will look something like the following:

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

The value associated with platform is what we need to identify. In the Winter ‘18 release, any value other than base, mobile,  portal, opi, or lpi is a custom platform. If platform does not appear in your request, then the good news is that you are not using a custom platform and you do not need to create a fix.  It’s possible that your integration uses more than one custom platform, so be sure to check all of your authentication calls.

Test your custom platform in Postman

One of my favorite ways to test REST API calls is to use Postman, so that’s what we’ll do here.  

A Postman Collection is a set of REST API calls and their associated headers, bodies, pre-request scripts, and tests.  I’ve created a Postman Collection you can use to test your fix.  The following steps will walk you through how to use this Postman Collection.

1. Download and install Postman if you have not previously installed it on your machine.
2. Download the Custom Platform Postman Collection.
3. Inside of Postman, click Import.
4. Import the Custom Platform Postman Collection you downloaded in step 2.
5. In the left pane, ensure the Collections tab is selected instead of the History tab.
6. Postman Environments allow you to store variables that can be used throughout your tests.  Create a new Postman Environment by clicking the gear icon toward the upper-right of the Postman app and then selecting Manage Environments.
   
   
7. In the Manage Environments dialog, click Add.
8. Name your new environment Custom Platform.
9. Add the following key-value pairs, substituting the appropriate values for your Sugar instance:
   1. url: the url of your Sugar instance (for example, http://localhost:8080/sugar)
   2. platform: the custom platform id you identified in the previous section
   3. rest_endpoint: /rest/v11
   4. username: the username associated with your Sugar administrator
   5. password:  the password associated with your Sugar administrator
10. Click Add.
11. Close the Manage Environments dialog.
12. Ensure the Custom Platform environment is selected.
    
    
13. Inside of the Custom platform API calls collection, select 1. Authenticate.  
    
    
14. You can explore the API call in the right pane.  You can click on the Body tab to see that this API call authenticates to your Sugar instance using the username, password, and platform you stored in your Postman Environment.  
    
    You can click on the Tests tab to see that the call runs two tests after it receives the response.  First, it checks that the response code is 200.  Second, it checks the access token is returned as part of the response.  The test code also stores the access token in the Postman Environment so that subsequent API calls will be able to use it.
    
    
15. Click Send to execute the request.
16. Scroll the right pane to see the results.  In the Body tab of the response, a message informing you an invalid platform was specified will be displayed.
    
    In the Test Results tab, two tests will be listed as failing.
    
    

At this point, the API call is failing because we have specified a custom platform that is not registered in our local Sugar instance.  The API call did not return an access token since our custom platform was invalid.  The remaining API calls in the collection require the access token we would have gotten from a successful Authenticate API call, so we will not execute those at this time.

Create the fix

Let’s create the fix!  We will create a module loadable package that registers one or more custom platforms.  Users of your Sugar integration will be able to install this module loadable package in their Sugar instances.

We will create the module loadable package from existing sample code.

1. Clone or download the 2017 branch of the UnCon GitHub repository:  https://github.com/sugarcrm/uncon/tree/2017.
2. In your local copy of the code, open custom-platform/src/custom/Extension/application/Ext/Platforms/rename-this-file.php in an editor.
3. Modify the contents of the file to include a line like $platforms[] = 'my-custom-platform'; for every custom platform your integration uses.
   
   
4. Save your changes.
5. Rename custom-platform/src/custom/Extension/application/Ext/Platforms/rename-this-file.php to something else like your integration’s name.
6. In your local copy of the code, open custom-platform/pack.php in an editor.
7. Around line 6, update the value of $packageID to reflect your integration’s name.  The $packageID will be part of the name of the module loadable package.
8. Around line 7, update $packageLabel to reflect your integration’s name.  The $packageLabel will be displayed in the Administrator’s UI when he or she installs the module loadable package.
9. Save your changes.
10. In a shell, navigate to the custom-platform directory.
11. Create the module loadable package by executing the pack.php script with the version number.
    
    The module loadable package will be created.

Install the fix

Now that you’ve generated the module loadable package, it’s time to install it!

1. In your browser, navigate to your local Sugar instance.
2. Login as an administrator.  You may be prompted to create a user profile if this is the first time you’ve logged in with this account.
3. In the upper-right corner, click the down arrow beside your profile picture and select Administration.
4. In the Developer Tools section, click Module Loader.
5. In the Modules section, upload the module loadable package you created in the previous section.  The module will be located in the custom-platform/releases directory.
6. Click the Install button on the row for your module loadable package.
7. Click Commit to install the package.
8. When the package has finished installing, click Back to Module Loader.  Your package will be listed as installed.

Test the fix in Postman

Now that you have registered your custom platform(s) using the module loadable package you created, it’s time to run our tests again in Postman.  This time, however, they will pass!

1. Open Postman.
2. In the upper-left corner, click Runner.  The Collection Runner opens.
3. In the Choose a collection or folder selection box, select Custom platform API calls.
4. In the Environment selection box, select Custom Platform.
5. Click Run Custom Platform API calls.  All six of the API calls and their associated tests will be executed.  The API calls authenticate using the custom platform you included as part of your Postman Environment and work through the CRUD (create, read, update, and delete) operations for the Contacts module.
6. If everything works, you will see 15 tests passed and 0 tests failed.
   
   

If you have more than one custom platform, repeat steps 1-6 above for each, being sure to update the custom platform stored in your Postman Environment before kicking off the Collection Runner.

Summary

Congratulations!  You’ve successfully created a module loadable package that registers your custom platform(s) in Sugar instances.  

In this tutorial, you tested your custom platform using Postman.  We recommend taking a few minutes to test your custom platform using your Sugar integration as well.  You’ll want to feel confident that you have successfully identified every custom platform your integration uses and that you haven’t accidentally made a typo with the custom platform name in your module loadable package.

Finally, don’t forget to give your module loadable package to anyone who uses your integration!  The package needs to be installed on every Sugar instance with which your integration interacts.

1385._Custom platform API calls original.postman_collection.json.zip