Editor’s Note: This post come from Angel Magaña, who has been a long time Sugar Community Member and co-author of Implementing SugarCRM 5.x (Packt Publishing – Sept 2010). Among the many community projects he’s lead and been a part of, he’s also developed language specific library for interacting with Sugar Web Services from .NET languages such as C# and VB.NET. He’s written a special post for us today to chat about the project and how .NET developers can leverage it to make working with Sugar Web Services and .NET a whole lot easier.
Some months back I wrote a brief article discussing some of the motivating principles behind the development of the CandyWrapper (CW) SugarCRM SOAP API wrapper for Microsoft .NET developers.
As mentioned in that article, the main idea behind the wrapper is to simplify the process of adopting the use of the SugarCRM SOAP API. It is specially helpful to those that are new to the world of SugarCRM, as it reduces or eliminates the need to know or understand nuances common to the API. Additional features it includes also make certain exchanges with the API a bit friendlier.
In this post, we will expand on the topic and examine some of these additional benefits not mentioned in the previous article. Let us begin with the most basic of needs, connecting to the API.
As would be expected with a web based application such as SugarCRM, connecting to the API requires one to provide the URL of the target installation. CW enhances the connection process in two ways; first, providing a method for validating the URL and secondly, including support for basic access authentication.
The obvious benefit of the first is to ensure the proper URL is being passed to the API, accomplished via the setURL(string sURL) method, whose sole parameter is the URL you wish to connect to. Here is an example (assuming oCW is the CW object in your code):
int iTemp = oCW.setURL("http://127.0.0.1:88/sugarcrm/soap.php");
You might notice that the method has one overload. This is the method used to provide support for basic access authentication, permitting you to connect to the SugarCRM SOAP API, even if it is sitting behind a password protected directory on your web server. To leverage this feature, simply pass the additional parameters
string sURL = "http://127.0.0.1:88/sugarcrm/soap.php"; string sHTTPUser = "web_user"; string sHTTPPass = "web_pass"; int iTemp = oCW.setURL(sURL, sHTTPUser, sHTTPPass, "Basic");
Once connected and ready to move on, you will find some additional helpful features. For one, CW eliminates the need to know the manner in which name value pairings of field and data should be formatted/declared to conform to the API. Instead, simply pass both as standard C# arrays (Dictionaries will be supported in the future).
Here is an example of the doSetEntry() method, used to insert a record into a module (in this case, an Opportunity). The arrays saNames() and saValues() represent the list of field names and corresponding data the record should contain, respectively.
string sID = oCW.doSetEntry(sSession, "Opportunities", saNames, saValues);
While on this topic, it is worth mentioning that methods in CW are named after their counterparts in the SugarCRM SOAP API. For example, doSetEntry() is derived from the equivalent set_entry() method provided by SugarCRM, likewise for doGetNoteAttachment(), whose equivalent is get_note_attachment() and so forth.
Note that not all the methods are represented in CW yet, but you should have access to those that are most commonly used for reading, searching and updating data. If you are unsure about the purpose of a method, the simple name translation should make it easy for you to find the proper section of the SugarCRM SOAP API documentation on the SugarCRM Developers Documentation for further information.
Returning to the main topic of the use of the arrays, there is also no need to understand how to decipher the results of searches performed via the API. CW will take the results provided by the API and convert them into a standard C# array of two dimensions for your use.
Some other advantages of CW are a bit more subtle.
For example, it is not widely documented, but references to module names within the API are actually case-sensitive. It, however, only becomes a factor if the SugarCRM instance that you are accessing is installed on a case-sensitive operating system such as Linux, a popular platform for many hosting providers. A common issue that comes up when this is not taken into account is that one’s code will work if one executes it against a SugarCRM instance installed on a Windows server, but the same exact code will fail if the SugarCRM instance is instead installed on a Linux server, even if the instance is a cloned version of the Windows implementation. i.e. using “opportunities” for the module name would work on Windows, but fail on Linux.
The wrapper compensates for this potential problem by automatically normalizing the module name references in the background, eliminating the need for developers to even know of this nuance in the API.
Note that CW does currently experience problems interacting with custom modules whose names are defined in all lower case characters. A solution to this problem is currently in progress.
One last tidbit worth mentioning are the helper methods that it includes. Currently, only one occupies the list, but a couple of others are pending final approval. The method in question is getMD5Hash(). It exists because the .NET framework does not include a method equivalent to PHP’s md5() method — it is actually a bit convoluted to generate the md5 hash in .NET when compared to PHP — and yet at the same time, methods such as doCreateAccount() require that the user’s password be passed as an md5 hash. Using the helper method would allow you to obtain that value by means of a simple call and proceed without further hassle.
Lastly, I recently released the code to CW and placed it on GitHub for the community to review, critique, improve. All suggestions and feedback are welcome, so please feel free to pay the GitHub project page a visit and participate.