Building a Client .NET for SugarCRM

Antonio Musarra's Blog The ideal solution for a problem Blog: http://musarra.wordpress.com

Mail: [email protected]

14/11/11 1 This document is issued with license Creative Commons Attribution-‐NonCommercial-‐ShareAlike

Building a client .NET for SugarCRM During this article we will see how to make a .NET client to access the

information recorded on the CRM system and use the client as the basis for the realization of a simple application .NET C# that is able to perform a series of elementary operations as: login, create a new contact and retrieve data.

SugarCRM (SugarCRM Inc.) exports to the outside of the interfaces that support SOAP and REST protocols, through these interfaces provide access to data through a set of CRUD operations (SugarCRM Inc.). The version of SugarCRM, which we will use, is the 6.1 Community Edition (SugarCRM Inc.).

We use the SOAP protocol for interaction between our application .NET and SugarCRM. There are different ways to create a C# SOAP client can communicate with a web service using .NET Framework (Microsoft) (Wikipedia). The steps to follow to reach our goal are:

• Generating the SOAP client • Compiling a SOAP client, such as .NET Library Assembly • Create the application .NET C#

The tools we use to complete the work are:

• .NET Framework SDK: Runtime and development tools. The reference version used in this article, is 4.0 of the framework. The Web services support is however also supported by previous versions of the framework.

• SharpDevelop: Open Source Development Environment for .NET. The reference version used in this article, is 4.1 (IC#Code)

The article is intended for an audience that has the basic knowledge of

software development .NET platform and in particular by using the C# language, as well as having some familiarity with the technology of web services.

The entire project source code made in the article is available on GitHub

repository at: https://github.com/amusarra/SugarCRM_CE_SOAP_V21_DotNetClientLibrary




1. The creation of SOAP Client To communicate with the SugarCRM web service you must create a proxy

class, a software element that allows us to transparently access the web service without worrying about the way this is called and used. The Proxy class is derived directly from the WSDL document that describes the web service. SugarCRM, version 5.5, introduced support for versioning to its API exposed as REST web service is SOAP, the version of the API reference is 2.1 (SugarCRM Inc.).

Through the SharpDevelop IDE, using the Add Web Reference feature, the creation of the proxy class is fairly straightforward. The creation of the proxy class is an operation that can also be performed using the SDK tools .NET, in Box 2 shows how to create and build.

Following a brief summary of the tasks that must run on SharpDevelop to create our assembly that will be used by the application .NET C# to communicate with SugarCRM:

• Creating a new Project / Solution • Creating the Proxy Class through the Add Web Reference • Building the Project

The process of creating the proxy class requires the WSDL of the web

service of SugarCRM, the WSDL can be remote (http / s) or local (file system). In our case we will use an instance of SugarCRM installed on the platform PHPFog (PHPFog) and can be reached at https://shirus-‐crm.phpfogapp.com. The figures shown to follow illustrate some of the important phases in of the process of creating the project of SharpDevelop.

Figure 1 The creation of new project as a Class Library.




The new project must be created using the Class Library template and specifying the profile .NET appropriate (in our case .NET Client Profile 4). The project will be created within a solution that will take the name specified in the Solution Name (see Figure 1).

Figure 2 Access to the function of Add Web Reference.

Once the project is created you can proceed with the creation of the proxy class using the Add Web Reference accessible through the context menu of the project.

Figure 3 Add Web Reference: SugarCRM web service's WSDL.

The WSDL document that describes the web service is accessible at https://shirus-‐crm.phpfogapp.com/service/v2_1/soap.php?wsdl. For reasons of simplicity I decided to simplify the Reference Name and Namespace than those proposed by default (see Figure 3). Once downloaded you can view the WSDL operations exposed by the web service through the tab "Available Web Services" (see Figure 4).




Figure 4 Operations exposed by the web service.

Figure 5 View of the project after the operation Add Web Reference.

Figure 5 shows the result obtained as the result of the Web Reference. The Reference.cs file, contains our Proxy Class. To complete this first phase it only remains to complete the project, the build process will create within the bin directory, the dll assembly.




2. The creation of the .NET C# Application Inside the solution created for the project of the Proxy class, we add a new

C# project which we will call, for example, SugarCRM_SOAP_Console_Client, using the template Windows Console (Windows Applications category).

Before proceeding further, we add the new project, a reference to System.Web.Services and SugarCRM_CE_SOAP_V21_ClientLibrary libraries. The reference to the libraries must be added using the Add Reference from the context menu of the project (see Figure 6 and Figure 7).

The sample application we are building must meet the following flow:

a) Log in to the specified user; b) Read some information about the system; c) Reading for information about who is logged in; d) Inserting a new contact; e) Reading data from the contact listed above; f) User logout.

Let us describe briefly what the Web service operations that we must use

in order to realize the specified flow and ways of using the application itself. In Table 1 are shown in order of the operations that use. For more information about SugarCRM API should consult the documentation.

Figure 6 Add Reference.




Figure 7 List of references.

Order Operations Description 1 get_server_info Returns a set of very useful information to identify the

details of installing SugarCRM (example: version, edition, etc ...).

2 login Perform the login process for the user specified, returns the session identifier (SessionID). The value of the SessionID is used in all operations that require the identification of the current user.

3 get_user_id Returns the ID of the user specifying the current session.

4 set_entry Insert an item for the specified module, for example, a contact, leads, accounts, etc ...

5 get_entry Returns an object that refers to the specified module. 6 logout Current user logs out. Table 1 List of Web service operations used by the application.

Our application (like Windows Console) will accept as input a username and password, plus the address (URL) you wish to connect SugarCRM instance. Usage: SugarCRMClient.exe {username} {password} [SugarCRM URL]

Listing 1 Using the client SugarCRM via console.

The use of the client does not necessarily require you to specify the URL of SugarCRM, if not specified, will use the URL from which you created the SOAP client (Proxy Class). Listing 1 shows how to use the command-‐line client and Listing 2 shows an example of use.

SugarCRMClient.exe amusarra amusarra https://shirus-crm.phpfogapps.com

Listing 2 Example of client usage.




The URL must not be to the WSDL document but rather address the root of SugarCRM, the application will then be responsible to construct the full URL of the API. The output of the application will be displayed on the console.

Summarily we have defined the functions required and how the application should be used, at this point we briefly analyze the code of our application. Code blocks are shown to follow the flow in the order indicated above. // Create a new instance of SugarCRM SOAP Proxy Client shirus.crm.phpfogapp.com.sugarsoap client = new shirus.crm.phpfogapp.com.sugarsoap(); if (SugarCRM_URL != null) { client.Url = SugarCRM_URL.AbsoluteUri + "service/v2_1/soap.php"; } /** * Step 1) Try login to SugarCRM istance with username and password */ // Prepare a User Auth Object shirus.crm.phpfogapp.com.user_auth userAuthInfo = new shirus.crm.phpfogapp.com.user_auth(); userAuthInfo.user_name = sugarCRMUserName; userAuthInfo.password = GetMD5Hash(sugarCRMPassword,false); // Execute a login as admin shirus.crm.phpfogapp.com.entry_value userSession = client.login(userAuthInfo, "SugarCRM Console Client 1.0.0", null); Listing 3 Login operation.

/** * Step 2) Get SugarCRM Server Info */ Console.WriteLine("SugarCRM EndPoint URL: " + client.Url); Console.WriteLine("SugarCRM Server Version: " + client.get_server_info().version); Console.WriteLine("SugarCRM Server Edition: " + client.get_server_info().flavor); Console.WriteLine("SugarCRM Server Time: " + client.get_server_info().gmt_time); /** * Step 3) Get logged user info */ String userId = client.get_user_id(userSession.id); Console.WriteLine("Welcome Your SessionID: " + userSession.id); Console.WriteLine("Get user data..."); Console.WriteLine("---------- BEGIN USER DATA ----------"); shirus.crm.phpfogapp.com.get_entry_result_version2 userInfo = client.get_entry(userSession.id, userSession.module_name, userId, null, null); foreach (shirus.crm.phpfogapp.com.name_value nameValue in userInfo.entry_list[0].name_value_list) { if (nameValue.value.Length > 0 && nameValue.name != "user_hash") { Console.WriteLine(nameValue.name + ": " + nameValue.value); }




} Console.WriteLine("---------- END USER DATA ----------"); Listing 4 SugarCRM and server information when the user logged.

/** * Step 4) Insert new contact */ Console.WriteLine("Try insert new Contact..."); Dictionary<string, string> contactsData = new Dictionary<string, string>(); contactsData.Add("first_name", "Antonio"); contactsData.Add("last_name","Musarra"); contactsData.Add("title", "IT Senior Consultant"); contactsData.Add("description", "Contacts created bye .NET SOAP Client"); contactsData.Add("email1","[email protected]"); shirus.crm.phpfogapp.com.name_value[] name_value_list = new shirus.crm.phpfogapp.com.name_value[contactsData.Count]; int i = 0; foreach (KeyValuePair<string, string> kvp in contactsData) { name_value_list[i] = new shirus.crm.phpfogapp.com.name_value(); name_value_list[i].name = kvp.Key; name_value_list[i].value = kvp.Value; i++; } shirus.crm.phpfogapp.com.new_set_entry_result contactResult = client.set_entry(userSession.id, "Contacts", name_value_list); Console.WriteLine("New Contact as Id:" + contactResult.id); Listing 5 Inserting a new contact.

/** * Step 5) Get My Contacts */ Console.WriteLine("Get data for Contacts: " + contactResult.id); Console.WriteLine("---------- BEGIN CONTACTS DATA ----------"); shirus.crm.phpfogapp.com.get_entry_result_version2 myContacts = client.get_entry(userSession.id, "Contacts", contactResult.id, null, null); foreach (shirus.crm.phpfogapp.com.name_value nameValue in myContacts.entry_list[0].name_value_list) { if (nameValue.value.Length > 0) { Console.WriteLine(nameValue.name + ": " + nameValue.value); } } Console.WriteLine("---------- END CONTACTS DATA ----------"); /** * Step 6) Logout */ client.logout(userSession.id); Console.WriteLine("User disconnected");




Listing 6 Retrieving contact data, and user logout.

I remember that the entire project is available on the public repository

GitHub https://github.com/amusarra/SugarCRM_CE_SOAP_V21_DotNetClientLibrary

Figure 8 Running the client SugarCRMClient [0].

Figure 9 Running the client SugarCRMClient [1].




Appendices SugarCRM on PHPFog The SugarCRM instance to which we referred is installed on the cloud platform PHPFog whose data access are as follows: URL: https://shirus-‐crm.phpfogapp.com User Account:

• Administrator => admin/admin • User => amusarra/amusarra

Box 1 Login information for the SugarCRM instance.

The creation of the Proxy Class via SDK .NET Through the web service's WSDL document, we can create the proxy class using the SDK tools .NET. The wsdl.exe tool allows us to generate the proxy class: wsdl /language:CS /v /n:shirus.crm.phpfogapp.com /o: SugarCRM_CE_SOAP_V21_ClientLibrary.cs https://shirus-crm.phpfogapp.com/service/v2_1/soap.php?wsdl The language parameter allows us to specify one of the languages supported by. NET Framework (in the example is required to generate a C # class). The result of the previous operation is the generation SugarCRM_CE_SOAP_V21_ClientLibrary.cs file, which contains the code for the Proxy Class for SugarCRM SOAP service. At this point we just have to fill in the Proxy Class, always using the SDK .NET: csc /t:library /out: SugarCRM_CE_SOAP_V21_ClientLibrary.dll SugarCRM_CE_SOAP_V21_ClientLibrary.cs /r:system.dll /r:system.xml.dll /r:system.web.services.dll In this way, we have compiled the class as a class library (/t: library) indicating the result of compiling the assembly SugarCRM_CE_SOAP_V21_ClientLibrary.dll, and using the metadata specified in the parameters /r. At this point the file SugarCRM_CE_SOAP_V21_ClientLibrary.dll, can be used as a library from. NET applications. Box 2 Creating the Proxy Class via the SDK. NET.




Bibliography Antonio Musarra's Blog. «PHP Application on the Cloud.» 30 August 2011. Antonio Musarra's Blog. Antonio Musarra. <http://musarra.wordpress.com/2011/08/30/php-‐application-‐on-‐the-‐cloud/>. IBM. «Best practices for Web services versioning.» 30 Jan 2004. IBM DeveloperWorks. Michael Ellis ([email protected]) Kyle Brown ([email protected]). <http://www.ibm.com/developerworks/webservices/library/ws-‐version/>. IC#Code. «SharpDevelop.» 2000. SharpDevelop. IC#Code. <http://sharpdevelop.net/OpenSource/SD/>. Microsoft. «.NET Framework.» 2011. Microsoft MSDN. Microsoft. <http://msdn.microsoft.com/en-‐en/netframework>. —. «Principles of Service Design: Service Versioning .» August 2005. Microsoft MSDN. John Evdemon. <http://msdn.microsoft.com/en-‐us/library/ms954726.aspx>. PHPFog. «Rock-‐solid Cloud Platform for PHP.» August 2010. Rock-‐solid Cloud Platform for PHP. Lucas Carlson. <https://www.phpfog.com/>. SOA World Magazine. «Design Strategies for Web Services Versioning.» 5 April 2004. SOA World Magazine. Anjali Anagol-‐Subbarao Chris Peltz. <http://soa.sys-‐con.com/node/44356>. SugarCRM Inc. «Sugar Community Edition Documentation.» 2010. Sugar Community Edition Documentation. SugarCRM Inc. <http://www.sugarcrm.com/crm/support/documentation/SugarCommunityEdition/6.1/-‐docs-‐Developer_Guides-‐Sugar_Developer_Guide_6.1.0-‐Chapter%202%20Application%20Framework.html#9000244>. —. «Sugar Community Edition Documentation.» 2010. Sugar Community Edition Documentation | SugarCRM -‐ Commercial Open Source CRM. SugarCRM Inc. <http://www.sugarcrm.com/crm/support/documentation/SugarCommunityEdition>. —. «Sugar Community Edition Documentation -‐ API Definition.» 2010. Sugar Community Edition Documentation. SugarCRM Inc. <http://www.sugarcrm.com/crm/support/documentation/SugarCommunityEdition/6.1/-‐docs-‐Developer_Guides-‐Sugar_Developer_Guide_6.1.0-‐Chapter%202%20Application%20Framework.html#9000303>. —. «SugarCRM -‐ Commercial Open Source CRM.» 2004. SugarCRM -‐ Commercial Open Source CRM. SugarCRM Inc. <http://www.sugarcrm.com/crm/>.




Wikipedia. «.NET Framework.» 15 July 2011. Wikipedia -‐ The Free Encyclopedia. Wikipedia. <http://en.wikipedia.org/wiki/.NET_Framework>.

Building a Client .NET for SugarCRM

Technology

Transcript of Building a Client .NET for SugarCRM