Getting started with SugarCRM REST API using UltraStudio

11 min readNov 21, 2017

In most of the integration solutions which are related to end customer information or customer oriented data, CRM will be one of the key components. CRM will act as the customer database, but with much more advanced application level features than a generic database.

In this blog post, I’m going to explain how to integrate with SugarCRM (CRM application for the example) using UltraStudio (integration capability provider for the tutorial).

Integrating with SugarCRM using UltraStudio

What is SugarCRM

As per this, SugarCRM is the world’s largest open source CRM (customer relationship management) software. Founded in 2004, over 7,000 customers and more than half a million users rely on SugarCRM to execute marketing programs, grow sales, retain customers, and create custom business applications.

What is UltraStudio

UltraStudio is a fully featured integration flow development environment which is built on top of IntelliJ IDEA. It has hundreds of Processors and Connectors out of the box to support integration with many other external entities such as SugarCRM, SAP, Amazon Web Services, Salesforce and many more. Because of that, using UltraStudio now you can easily create complex enterprise integration flows just by drag-n-drop. For more information on UltraStudio, refer its documentation.

Okay, now we know our key components that we are going to use in this blog post. Let’s go to the use case scenario that we are going to address here as the example.

Use case scenario

Let’s assume that Company XYZ needs to facilitate a new feature to their customers to do bank transactions via the mobile phone. For that, users are required to register for this value-added service via an SMS. Company XYZ already has an SMS gateway which has the ability to invoke a web service depending on the configured type of SMS messages. They have decided to use SugarCRM to keep customer information for these value-added services. As the first use case of this new feature, they should provide the ability for end users to register for this service via an SMS message.

As per the design, end users will send an SMS with their information in a pre-defined format to a pre-defined number. Based on this number and format, SMS Gateway will identify this as a registration request and it will do a web service call (simply an HTTP call with SOAP message body) with the user information. In this example, I’m going to explain how do we expose a web service to handle user registration by integrating with SugarCRM.

So web service should be able to,

accept SOAP requests
extract out required parameters from the request message
set those parameters to the SugarCRM request
send a message to SugarCRM with extracted data
handle the response from the SugarCRM
send back the response status to SMS Gateway as a SOAP message

One more thing that I should highlight here. SugarCRM exposes a REST API for its clients to connect with it programmatically. You can find documentation for the REST API from here. However, if you are going to use REST API directly, you have to read its complete documentation, believe me, it will be a little bit hard to implement it from the scratch. The beauty of the SugarCRM Egress Connector is, it hides all the complexity from the user and user doesn’t require to know anything about the underline REST API. From the user’s point of view, it’s just configuring required values for each parameter for the relevant entity — in this case, for account management, the user just have to configure relevant parameter value from Account name, email etc. The user doesn’t have to worry about what is the message format that should be sent to SugarCRM side, how to manage access token etc.

Implementation

Now we are going to implement above-explained flow using UltraStudio. If you are new to UltraStudio, you just have to do is download and install it in your local computer — if you have IntelliJ IDEA in your computer, you just have to download the UltraStudio plugin and install it on top of the existing IDEA installation, if you are new to IntelliJ IDEA as well, no need to worry, you can download the complete distribution of UltraStudio. You can download UltraStudio from here. Refer this to the installation guide.

Once you have installed UltraStudio, that’s it, you don’t need any other prior-knowledge to follow this. UltraStudio has a simple and intuitive user interface which make sure, users can easily get familiar with it. Give it a try, I’m pretty sure, that you will love it :-)

For this example, let’s assume that we are getting an input message like this from SMS Gateway,

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soap="http://soap.services.samples/">
   <soapenv:Body>
       <soap:registerUser>
           <request>
               <name>John Doe</name>
               <email>john@org.com</email>
               <description>John Doe is a SMS based registered user for bank transaction service</description>
               <phoneNo>0094793874987</phoneNo>
           </request>
       </soap:registerUser>
   </soapenv:Body>
</soapenv:Envelope>

And we need to respond back to SMS Gateway with a message like this,

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soap="http://soap.services.samples/">
    <soapenv:Body>
        <soap:registerUser>
            <response>
                <status>Success</status>
                <userId>registered-user-account-id</userId>
            </response>
        </soap:registerUser>
    </soapenv:Body>
</soapenv:Envelope>

Okay, for the implementation, let’s go through step by steps,

First, create a project using UltraStudio using File -> New -> Project and then select the option “Empty Ultra Project” using left tab go to the next option of the wizard until you see the connectors list.

From the connectors list, you have to select HTTP NIO Connector and SugarCRM Connector. After that go to the processor list to select XML Processing element and Logger processing element and finalize the project creation wizard by giving an appropriate name. Once you create your project it will take a couple of minutes to download required dependencies and set up the environment.

The next thing is, you have to create an integration flow configuration file for your project in the src/main/conf directory. For that, you just have to do is right-click on the conf directory and go to New -> Integration Flow option as below,

Then you should see two views of your integration flow — text view with XML configuration and design view for drag and drop based configuration. Obviously, it’s drag and drop based view that we are going to use for this example.

Then let’s build our integration flow as follows, with an HTTP ingress connector, logging processing element and a SugarCRM egress connector along with a SugarCRM Accounts Operation.

Let’s see how these elements should be configured to implement our solution.

HTTP Ingress Connector (1)

HTTP Ingress Connector is the starting point our web service which should accept HTTP calls over a given port and service path. For this example, let’s consider port is 8280 and service path is “/service/user-registration”. So in the basic tab of HTTP Ingress Connector configuration, it should configure as below,

Port — 8280
Service Path — /service/user-registration

Logger Processing Element (2)

This is an optional element which is added to make it more understandable when we are running our project. Let’s configure this element to log receiving message payload content as an INFO level log (generally message payload should be logged in TRACE level, but for this example let’s go with INFO level)

Log Template — Message received with payload : @{message.payload}
Log Level — INFO

As you have noticed we have used placeholder based notation to include message payload to the log message. Generally, this placeholder based notation is supported throughout the framework for most of the user configured values

XPath String Extractor (3)

Next, we need to extract required values from the input message. This element is supposed to extract account name from the input message. For that, it should be configured with the correct XPath and variable name can be any name which can be referred later in the SugarCRM Accounts Operation. Let’s configure it as below,

Variable Name — sugar.account.name
XPath — //request/name

XPath String Extractor (4)

Next, we need to extract the email address from the input message, for that let’s configure the next XPath String Extractor as below,

Variable Name — sugar.account.email
XPath — //request/email

XPath String Extractor (5)

Last XPath String Extractor element should be configured to extract the phone number from the input message.

Variable Name — sugar.account.phoneNo
XPath — //request/phoneNo

SugarCRM Egress Connector (6)

SugarCRM Egress connector is responsible for calling SugarCRM server based on the provided URL and credentials. This will handle the connection between our application and SugarCRM server while managing access token for authentication.

SugarCRM Server Base URL — https://<your-sugarcrm-account-base-url>/rest/v10
SugarCRM Username — sugar-crm-user
SugarCRM Password — sugar-crm-password

SugarCRM Accounts Operation (7)

Accounts operation is responsible for managing Accounts on the SugarCRM side. This can be used to do CRUD operations on SugarCRM accounts. For this example, we need to create an Account from the information received through the input message. By now we have extracted out required values for Scope variables from above three XPath String Extractor elements. Here we just have to use those variable names for account name, email and phone number as below,

Operation — CREATE — since we are going to create an account
Account Name — @{variable.sugar.account.name}
Account Type — Customer
Email Addresses — @{variable.sugar.account.email}
Description — @{variable.sugar.account.name} is a SMS based registered user for bank transaction service
Phone Number — @{variable.sugar.account.phoneNo}

Variable values can be used with the @{variable.} placeholder notation for any input value.

JSON Path Extractor (8)

Now we need to process the received response from the SugarCRM and construct the response message to the SMS Gateway. As per the requirement, we should include the id of the created account in the response message. SugarCRM will send the created account id in the response message for our request, we just have to do is extract it out and construct our response message. To extract out the account id from the response message we need a JSON Path Extractor element with the following configuration,

Variable Name — sugarcrm.account.id
JSON Path — id

This will extract out value which will be receiving as the id and set that value as a scope variable with name “sugarcrm.account.id”

String Payload Setter (9)

Now we need to set the response message payload. For that, we just need to insert extracted account id and construct the response message. For this example, let’s assume that rest of the content is constant in the response message. So how are we going to construct that?

As you have already guessed, we can use the same placeholder notation and insert the account id to the response message. So “String Payload” parameter should be configured from the following value,

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soap="http://soap.services.samples/">
    <soapenv:Body>
        <soap:registerUser>
            <response>
                <status>Success</status>
                <userId>@{variable.sugarcrm.account.id}</userId>
            </response>
        </soap:registerUser>
    </soapenv:Body>
</soapenv:Envelope>

Run it…

Now we are done!!! now we can run our project. Before running your project, you have to build it via Maven. For that, you have to go to the Terminal window (View -> Tool Windows -> Terminal, shortcut should be control + f12) and run the command “mvn clean install”.

Once it’s built, you have to add a run configuration to the IDEA. For that go running -> Edit Configurations. There you can add new Run Configuration by clicking the plus button at the top left corner of the window. Then you have to select the UltraESB-X Server type as below and click the OK button (since we have built the project, IDEA will fill all the values with correct default values)

Now all set, you can click on the Run button (play button in green) to turn your project. When you run the project you should see few log lines in your console. Once you see log line starting with “XContainer AdroitLogic UltraStudio UltraESB-X server started successfully …” you can identify that your project is successfully started and it’s ready to work as a web service to process input messages.

Test it…

One more interesting thing that I love about UltraStudio is it has almost all the features to build and test your integration flow. Now we want to test your project by sending an HTTP request to the configured port and service path. How are we going to do that? Do we need some other external tool? No, we don’t… Fortunately, UltraStudio has a toolbox (View -> Tool Windows -> Ultra Studio Toolbox) to test your projects which is capable of acting as an HTTP client, JMS client, Socket client etc. For your case, let’s create an HTTP client by clicking on the Plus button in the toolbox. Then we can set the request URL as http://localhost:8280/service/user-registration and set the payload as above SOAP input message. Then click on the Play button to send the request to our project that we have started. Then you should be able to see a SOAP message with the account ID as the response message as expected.

If you are more interested in how this flow works and what were the intermediate states of our request, you can do that by clicking on the following icon of your integration flow view.

Once you click on that icon, you will see the execution path get highlighted with the green color. On that highlighted path you can see message context details by clicking on the message icon on the highlighted path. If you want to check the message context status after going through all the XPath String Extractor elements, you should click on the message icon after the fifth element and it will show extracted scope variables as below,

Handling Error Scenarios

If you are more curious and need to know how do we handle error scenarios like what will happen if the received message doesn’t have expected information like account name, email etc? In this case, it will fail to process the request and respond to the client with 500 — Internal server error response. If you want to handle that error, you can use the error port of XPath String Extractor element. Almost all the elements in the UltraStudio has an error port which will use to emit the message when there is a processing error. If you want to handle those errors, you can connect processing elements to that port and process the exception to handle the error.

That’s it…!!!

I hope you have enjoyed the blog post as well as the cool features of UltraStudio. Feel free to share your views/ comments. If you have any issues related to the implementation, I’m more than happy to help you.

SugarCRM is registered trademark of SugarCRM Inc. in the United States and/or other countries