SugarSoap In java

SugarCRM provides Web Services API via the NuSOAP PHP implementation of the SOAP protocol. The SugarSoap API are built using the NuSOAP library and included in the Sugar Community Edition, Sugar Professional Edition and Sugar Enterprise Edition.
This guide leads you through the steps of creating sugarsoap clients stubs In java using Xfire .Codehaus XFire is a next-generation java SOAP framework. We will use it to consume the SugarSoap webservice in Java clients.

1- Locate The SugarSoap WSDL file:

This guide suppose you already have a working sugarcrm installation. If you don’t have one, download and install the free Sugar Community Edition . Refer to section Installing and Upgrading Sugar to guide you through the installation procedure.
For example, In my Linux machine I unpacked the Sugar Community Edition 5.5.0 bundle into my apache server web apps directory ‘/srv/www/htdocs/SugarCE-Full-5.5.0’ . After completing the installation, I access my local sugarcrm application by browsing to URL : http://localhost/SugarCE-Full-5.5.0/. This URL could vary depending on your own choices of server, host and port. For the rest of this guide I’ll use the reference $sugar_base_url to refer to the base URL you use to access your sugarcrm installation (for me, $sugar_base_url =http://localhost/SugarCE-Full-5.5.0/ ).

The SugarSoap WSDL (Web Services Description Language) is located at:

in my case it’s located at http://localhost/SugarCE-Full-5.5.0/soap.php?wsdl . Mark well this sugarsoap WSDL URL because we will need it for generating the sugarsoap clients stubs.

2- Getting XFire and other libraries:

To use Xfire we need the necessary library files. Go to xfire web site download page and download the file ( replace ‘x.x.x’ by the version number .the latest xfire version is at the time of writing this guide).
unzip it in a local folder. add the xfire-all-1.2.6.jar file from the distribution and its lib directory into your project classpath.
If you are using eclipse IDE, you can get the Xfire Eclipse plugin which is a nice and easy to use tool for generating Xfire clients stubs from WSDL files.

3.Generating SugarSoap Clients stubs with Xfire:

Ant is a useful and flexible tool to automate the building of your java project. Most java IDE generates a build.xml file for you , so why not use Ant to generate our sugarsoap clients stubs?

Edit your build .xml file and add the following ant target at the end of the file :

<target name="wsGen">

        <!-- Replace ${basedir} by your project base directory  and ${sugar_base_url} by your sugar URL (ex : http://localhost/SugarCE-Full-5.5.0-->

        <property name="dependencyfinder.home" value="${basedir}"/>
        <path id="dependencyfinder">
            <pathelement location="${basedir}/lib"/>
            <fileset dir="${basedir}/lib">
                <include name="**/*.jar"/>

        <taskdef name="wsgen">

        <wsgen overwrite="true"

${basedir}/lib points to the directory where you copied all your xfire distribution jar files and xfire distribution lib folder jars.

From your command line change to your build.xml file directory and run command :

$ ant wsGen

this will generate the SugarSoap clients stubs under src directory in java package :
package holds the main sugarsoap java stubs classes mainly the class Sugarsoap

4.Writing a SugarSoap Java client:

Now it’s time to write a simple java client to test our sugarsoap service. Below is a java code snippet that demonstrates how to login to your sugarcrm web application :

import javax.xml.rpc.ServiceException;

public class SugarTest {

	Sugarsoap service = new SugarsoapLocator();
	SugarsoapPortType soap = null;
	public static void main(String[] arg) {

		try {
			soap = service.getsugarsoapPort(new URL("http://localhost/SugarCE-Full-5.5.0/"));
			String session = soap.login("your username", "your password",
					" sugarsoap test");
			if (session == null)
						.println("there was an error connecting to sugarcrm service");
						.println("login to sugar service successfull. sessionId="
								+ session);

		} catch (MalformedURLException e) {
			// TODO Auto-generated catch block

		} catch (ServiceException e) {
			// TODO Auto-generated catch block



	 * Logs the user into the Sugar application.
	 * @param username
	 * @param password
	 * @param application
	 * @return sugar session id
	String login(String username, String password, String application) {

		Set_entry_result loginRes = null;
		String session = null;

		try {"connecting to " + this.sugarURL + " as " + username);
			User_auth user_auth = new User_auth(username,
					MD5.getHashString(password), "1");
			loginRes = this.soap.login(user_auth, application);

			if (loginRes == null) {
				// null result means something wrong went with authentication
				return null;
			session = loginRes.getId();
			String userid = this.soap.get_user_id(session.getId());
			boolean error = (!loginRes.getError().getNumber().equals("0"));

			if (error) {

				if (userid == "-1") {
					String text = "Error connecting to "
							+ this.sugarURL
							+ ": Connection is available, but SOAP is not responsive due to PHP configuration.";
					_logger.error("Error initializing connection:" + text);

					return null;


				_logger.error("sugar login error :"
						+ loginRes.getError().getNumber() + " "
						+ loginRes.getError().getName() + " "
						+ loginRes.getError().getDescription());
				return null;

			} else {
				// sugar login successful"login to sugar application successful");


		} catch (Exception e) {

			// Caught an unexpected exception!
			_logger.error(e.getMessage(), e);
			return null;

		return session;


this snippet simply create a service instance and use it to create a soap Object instance. soap Object is the entry class for all sugarsoap methods.
The login() method snippet describe how to connect to your sugarcrm instance and returns the sugar session id if login is successfull.Note that you need to encode your sugar password using the MD5 algorithm.


Once you complete the previous steps in setting up sugarsoap java stubs clients with xfire, you can start exploring and using the power of the sugarcrm services by calling the various sugarsoap API methods .
xfire is not the only java webservice library to generate sugarsoap client. you can also use other java webservice tools like axis and CXF and others. in a comming post I’ll describe a simple method to generate sugarsoap client using eclipse IDE and axis2.
The supported calls in the official sugarsoap API are listed and described in this section of the Sugar Developer Guide: Web Services