Antonio	  Musarras	  Blog	  The	  ideal	  solution	  for	  a	  problem	                                                   ...
Antonio	  Musarras	  Blog	  The	  ideal	  solution	  for	  a	  problem	                                                   ...
Antonio	  Musarras	  Blog	  The	  ideal	  solution	  for	  a	  problem	                                                   ...
Antonio	  Musarras	  Blog	  The	  ideal	  solution	  for	  a	  problem	                                                   ...
Antonio	  Musarras	  Blog	  The	  ideal	  solution	  for	  a	  problem	                                                   ...
Antonio	  Musarras	  Blog	  The	  ideal	  solution	  for	  a	  problem	                                                   ...
Antonio	  Musarras	  Blog	  The	  ideal	  solution	  for	  a	  problem	                                                   ...
Antonio	  Musarras	  Blog	  The	  ideal	  solution	  for	  a	  problem	                                                   ...
Antonio	  Musarras	  Blog	  The	  ideal	  solution	  for	  a	  problem	                                                   ...
Antonio	  Musarras	  Blog	  The	  ideal	  solution	  for	  a	  problem	                                                   ...
Antonio	  Musarras	  Blog	  The	  ideal	  solution	  for	  a	  problem	                                                   ...
Antonio	  Musarras	  Blog	  The	  ideal	  solution	  for	  a	  problem	                                                   ...
Upcoming SlideShare
Loading in …5
×

Building a Client .NET for SugarCRM

4,973 views

Published on

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.

Published in: Technology
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
4,973
On SlideShare
0
From Embeds
0
Number of Embeds
1,258
Actions
Shares
0
Downloads
58
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

Building a Client .NET for SugarCRM

  1. 1. Antonio  Musarras  Blog  The  ideal  solution  for  a  problem   Blog:  http://musarra.wordpress.com   Mail:  antonio.musarra@gmail.com    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                    14/11/11   1   This  document  is  issued  with  license  Creative  Commons  Attribution-­‐NonCommercial-­‐ShareAlike      
  2. 2. Antonio  Musarras  Blog  The  ideal  solution  for  a  problem   Blog:  http://musarra.wordpress.com   Mail:  antonio.musarra@gmail.com     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 (SugarCRMInc.).   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.    14/11/11   2   This  document  is  issued  with  license  Creative  Commons  Attribution-­‐NonCommercial-­‐ShareAlike      
  3. 3. Antonio  Musarras  Blog  The  ideal  solution  for  a  problem   Blog:  http://musarra.wordpress.com   Mail:  antonio.musarra@gmail.com     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  services  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).      14/11/11   3   This  document  is  issued  with  license  Creative  Commons  Attribution-­‐NonCommercial-­‐ShareAlike      
  4. 4. Antonio  Musarras  Blog  The  ideal  solution  for  a  problem   Blog:  http://musarra.wordpress.com   Mail:  antonio.musarra@gmail.com        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.            14/11/11   4   This  document  is  issued  with  license  Creative  Commons  Attribution-­‐NonCommercial-­‐ShareAlike      
  5. 5. Antonio  Musarras  Blog  The  ideal  solution  for  a  problem   Blog:  http://musarra.wordpress.com   Mail:  antonio.musarra@gmail.com     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.    14/11/11   5   This  document  is  issued  with  license  Creative  Commons  Attribution-­‐NonCommercial-­‐ShareAlike      
  6. 6. Antonio  Musarras  Blog  The  ideal  solution  for  a  problem   Blog:  http://musarra.wordpress.com   Mail:  antonio.musarra@gmail.com      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.comListing  2  Example  of  client  usage.  14/11/11   6   This  document  is  issued  with  license  Creative  Commons  Attribution-­‐NonCommercial-­‐ShareAlike      
  7. 7. Antonio  Musarras  Blog  The  ideal  solution  for  a  problem   Blog:  http://musarra.wordpress.com   Mail:  antonio.musarra@gmail.com     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 Clientshirus.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 Objectshirus.crm.phpfogapp.com.user_auth userAuthInfo = newshirus.crm.phpfogapp.com.user_auth();userAuthInfo.user_name = sugarCRMUserName;userAuthInfo.password = GetMD5Hash(sugarCRMPassword,false);// Execute a login as adminshirus.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 inuserInfo.entry_list[0].name_value_list) { if (nameValue.value.Length > 0 && nameValue.name != "user_hash") { Console.WriteLine(nameValue.name + ": " + nameValue.value); }14/11/11   7   This  document  is  issued  with  license  Creative  Commons  Attribution-­‐NonCommercial-­‐ShareAlike      
  8. 8. Antonio  Musarras  Blog  The  ideal  solution  for  a  problem   Blog:  http://musarra.wordpress.com   Mail:  antonio.musarra@gmail.com    }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","antonio.musarra@gmail.com");shirus.crm.phpfogapp.com.name_value[] name_value_list = newshirus.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 inmyContacts.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");  14/11/11   8   This  document  is  issued  with  license  Creative  Commons  Attribution-­‐NonCommercial-­‐ShareAlike      
  9. 9. Antonio  Musarras  Blog  The  ideal  solution  for  a  problem   Blog:  http://musarra.wordpress.com   Mail:  antonio.musarra@gmail.com    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].        14/11/11   9   This  document  is  issued  with  license  Creative  Commons  Attribution-­‐NonCommercial-­‐ShareAlike      
  10. 10. Antonio  Musarras  Blog  The  ideal  solution  for  a  problem   Blog:  http://musarra.wordpress.com   Mail:  antonio.musarra@gmail.com    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  services  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.dllSugarCRM_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.            14/11/11   10   This  document  is  issued  with  license  Creative  Commons  Attribution-­‐NonCommercial-­‐ShareAlike      
  11. 11. Antonio  Musarras  Blog  The  ideal  solution  for  a  problem   Blog:  http://musarra.wordpress.com   Mail:  antonio.musarra@gmail.com    Bibliography  Antonio  Musarras  Blog.  «PHP  Application  on  the  Cloud.»  30  August  2011.  Antonio  Musarras  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  (msellis@ca.ibm.com)  Kyle  Brown  (brownkyl@us.ibm.com).  <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/>.  14/11/11   11   This  document  is  issued  with  license  Creative  Commons  Attribution-­‐NonCommercial-­‐ShareAlike      
  12. 12. Antonio  Musarras  Blog  The  ideal  solution  for  a  problem   Blog:  http://musarra.wordpress.com   Mail:  antonio.musarra@gmail.com    Wikipedia.  «.NET  Framework.»  15  July  2011.  Wikipedia  -­‐  The  Free  Encyclopedia.  Wikipedia.  <http://en.wikipedia.org/wiki/.NET_Framework>.      14/11/11   12   This  document  is  issued  with  license  Creative  Commons  Attribution-­‐NonCommercial-­‐ShareAlike      

×