Getting started with SugarCRM REST API using UltraStudio

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

What is UltraStudio

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

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
Web service flow diagram

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

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.

Integration flow of the implementation

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

HTTP Ingress Connector (1)

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

Logger Processing Element (2)

  • 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)

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

XPath String Extractor (4)

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

XPath String Extractor (5)

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

SugarCRM Egress Connector (6)

  • 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)

  • 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)

  • 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)

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…

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…

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

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

Call To Action

  • Comment. Share your views on this article.
  • Follow me. Manjula Piyumal to receive updates on articles like this.
  • Keep in touch. LinkedIn, Twitter

Originally published at manjulapiyumal.blogspot.com.

Software Engineer who loves to work on integration space. I speak Java, Scala, Javascript, English and Sinhala

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store