webcrm API Getting Started

Transcription

1 webcrm API Getting Started / TS Contents.NET Application with autogenerated proxy class... 2.NET Application sending SOAP messages directly... 10

2 .NET Application with auto generated proxy class The following example describes how to add a Web Service link to the webcrm API, get an auto generated proxy class and use it to manipulate webcrm data. The description is based on Visual Studio 2010, but the same can be done with small differences also under Visual Studio 2005 and all later versions. Step 1. Go to webcrm and the webcrm API URL - see the below screenshot.

3 Step 2. It makes sense to check if the URL is workable. For example, it could be forbidden according to some network security rules. If you open the URL with any Internet browser you should get something like this.

4 Step 3. Open Visual Studio and create a new project.

5 Step 4. Add a Service Reference

6 Step 5. Copy the URL stored at the Step #1 into the Address field.

7 Step 6. Click the Go button to make the framework analyze the URL and discover the service. If you get a security warning then just confirm that the URL is trusted. After pressing OK you should see the new reference added under Service References folder. Together with the reference you will get an endpoint specification in the config file. It will be similar to the below: <?xml version="1.0" encoding="utf-8"?> <configuration> <system.servicemodel> <client> <endpoint address=" binding="basichttpbinding" bindingconfiguration="webcrmapisoap" contract="servicereference1.webcrmapisoap" name="webcrmapisoap" /> </client> </system.servicemodel> </configuration>

8 Step 7. Now we ve got a couple of classes generated automatically based on the web-service URL. These classes enable working with the web-service in a simple and intuitive way. You do not need bothering about SOAP requirement neither of encoding formats. The below is a code snippet based on the generated classes. Imports System.Net Imports System.Net.Security Imports System.Security.Cryptography.X509Certificates Imports ConsoleApplication1.ServiceReference1 Module Module1 Sub Main() ' Add handler for SSL validation ServicePointManager.ServerCertificateValidationCallback = AddressOf AcceptAllCertifications ' Instantiate proxy class Dim proxy As New WebCrmApiSoapClient() ' Authenticate Dim dbncode As String = "crmaccount" Dim username As String = "username" Dim password As String = "password" Dim errorstatus As ErrorStatus = Nothing Dim ticket As TicketHeader = proxy.authenticate( dbncode, username, password, errorstatus) ' Do something useful, for example, add new organisation Dim data As New WebCrmData With {.Pairs = New KeyValuePair() { New KeyValuePair With {.Key = "1_Name",.Value = "Wates Construction АБВ"}, New KeyValuePair With {.Key = "1_Division_name",.Value = "Sharston æøåæø"}, New KeyValuePair With {.Key = "1_Telephone",.Value = " "}, New KeyValuePair With {.Key = "1_Fax",.Value = " "}, New KeyValuePair With {.Key = "1_Post_code",.Value = "M22 4BJ"} }} ' Note that text values can directly contain Danish, Cyrillic ' or other characters as shown above ' Request data of the added organisation back Dim result As WriteToWebCrmResult = proxy.writetowebcrm(ticket, DataEntityType.Organisations, 0, 0, data) Dim organisationid As Long = result.id

9 Dim collection As WebCrmDataCollection = proxy.readfromwebcrmbyid(ticket, DataEntityType.Organisations, organisationid, organisationid) ' Close session errorstatus = proxy.endsession(ticket) ticket = Nothing End Sub ''' <summary> ''' Encapsulates SSL certificate validation. ''' Add here your own logic or just let it return <c>true</c> in all cases. ''' </summary> Public Function AcceptAllCertifications( ByVal sender As Object, ByVal certification As X509Certificate, ByVal chain As X509Chain, ByVal sslpolicyerrors As SslPolicyErrors) As Boolean Return True End Function End Module

10 .NET Application sending SOAP messages directly If you cannot simplify your work by using auto-generated classes the following notes can be useful. 1. Go to webcrm and take URL to webcrm API service.

11 2. Get WSDL schema using the URL (+?wsdl parameter). The schema should be applied when you build your SOAP messages.

12 3. If it s too complicated to understand WSDL schema it can be helpful to visit the test page of webcrm API to see how specific requests should look.

13 4. The Test page helps you build the SOAP messages. You only have to select the service method and enter parameter values. Click the Generate Request button to generate the SOAP message and the Send Request button to send it to webcrm API.

14 5. Note that there is some encoding logic that you should be aware of. SOAP does not enable characters &, <, >, and. Instead they should be replaced with &, <, >, " and &apos; correspondingly. If you use the Test page to generate SOAP message then this will be handled automatically. The SOAP messages should be always sent with UTF-8 encoding. Below is a code example: Imports System.Net Imports System.Text Imports System.Net.Security Imports System.Security.Cryptography.X509Certificates Module Module1 Sub Main() Dim command1 As String = "<?xml version=""1.0"" encoding=""utf-8""?>" _ & "<soap12:envelope " _ & " xmlns:xsi="" " _ & " xmlns:xsd="" " _ & " xmlns:soap12="" _ & " <soap12:body>" _ & " <Authenticate xmlns="" _ & " <dbncode>account</dbncode>" _ & " <username>username</username>" _ & " <password>password</password>" _ & " </Authenticate>" _ & " </soap12:body>" _ & "</soap12:envelope>" Dim command2 As String = "<?xml version=""1.0"" encoding=""utf-8""?>" _ & "<soap12:envelope " _ & " xmlns:xsi="" _ & " xmlns:xsd="" _ & " xmlns:soap12="" _ & " <soap12:header>" _ & " <TicketHeader xmlns="" _ & " <Guid>{0}</Guid>" _ & " </TicketHeader>" _ & " </soap12:header>" _ & " <soap12:body>" _ & " <WriteToWebcrm xmlns="" _ & " <entitytype>organisations</entitytype>" _ & " <organisationid>0</organisationid>" _ & " <recordid>0</recordid>" _ & " <data>" _ & " <ErrorStatus>" _ & " <Message></Message>" _ & " <Code>0</Code>" _ & " </ErrorStatus>" _

15 & " <Pairs>" _ & " <KeyValuePair><Key>1_Name</Key>" _ & " <Value>Wates Construction АБВ</Value></KeyValuePair>" _ & " <KeyValuePair><Key>1_Division_name</Key>" _ & " <Value>Sharston æøåæø</value></keyvaluepair>" _ & " <KeyValuePair><Key>1_Telephone</Key>" _ & " <Value> </Value></KeyValuePair>" _ & " <KeyValuePair><Key>1_Fax</Key>" _ & " <Value> </Value></KeyValuePair>" _ & " <KeyValuePair><Key>1_Post_code</Key>" _ & " <Value>M22 4BJ</Value></KeyValuePair>" _ & " </Pairs>" _ & " </data>" _ & " </WriteToWebcrm>" _ & " </soap12:body>" _ & "</soap12:envelope>" Dim command3 As String = "<?xml version=""1.0"" encoding=""utf-8""?>" _ & "<soap12:envelope " _ & " xmlns:xsi="" _ & " xmlns:xsd="" _ & " xmlns:soap12="" _ & " <soap12:header>" _ & " <TicketHeader xmlns="" _ & " <Guid>{0}</Guid>" _ & " </TicketHeader>" _ & " </soap12:header>" _ & " <soap12:body>" _ & " <ReadFromWebcrmById xmlns="" _ & " <entitytype>organisations</entitytype>" _ & " <organisationid>{1}</organisationid>" _ & " <recordid>{1}</recordid>" _ & " </ReadFromWebcrmById>" _ & " </soap12:body>" _ & "</soap12:envelope>" ' Add handler for SSL validation ServicePointManager.ServerCertificateValidationCallback = AddressOf AcceptAllCertifications ' Submit authenticate SOAP message Dim uri As String = " Dim result1 As String = SubmitRequest(uri, command1) Dim ticketguid As String = GetTicketGuid(result1) ' Submit SOAP message to add one new organisation Dim result2 As String = SubmitRequest(uri, String.Format(command2, ticketguid)) Dim organisationid As String = GetOrganisationId(result2) ' Submit SOAP message to get the added organization back from webcrm Dim result3 As String = SubmitRequest(uri, String.Format(command3, ticketguid, organisationid))

16 End Sub Private Function SubmitRequest(ByVal uri As String, ByVal data As String) As String Dim client As New WebClient() client.encoding = Encoding.UTF8 client.headers.add("content-type", "text/xml; charset=utf-8") Return client.uploadstring(uri, data) End Function Private Function GetTicketGuid(ByVal response As String) As String Dim guid As String = String.Empty Dim data As String = response.tolower() If (data.indexof("</ticketheader>") > -1) Then data = data.substring(0, data.indexof("</ticketheader>")) If (data.indexof("</guid>") > -1) Then data = data.substring(0, data.indexof("</guid>")) data = data.substring(data.length - 36) guid = data End If End If Return guid End Function Private Function GetOrganisationId(ByVal response As String) As String Dim id As String = String.Empty Dim data As String = response.tolower() If (data.indexof("</id>") > -1) Then data = data.substring(0, data.indexof("</id>")) data = data.substring(data.lastindexof(">") + 1) id = data End If Return id End Function ''' <summary> ''' Encapsulates SSL certificate validation. ''' Add here your own logic or just let it return <c>true</c> in all cases. ''' </summary> Public Function AcceptAllCertifications( ByVal sender As Object, ByVal certification As X509Certificate, ByVal chain As X509Chain, ByVal sslpolicyerrors As SslPolicyErrors) As Boolean Return True End Function

17 End Module