Calling External Web Services from Salesforce.com – Part III: Building an Apex class that calls your web service

Part I: Hosting your web service
Part II: Opening your web service to the internet
Part III: Building an Apex class that calls your web service

In Part I & Part II of this series, I discussed the details of hosting a web service on your computer and exposing it to the internet. If you are working in an enterprise/corporate network environment, your web service is almost always not exposed to the internet. If so, I would encourage you to also read Part I & II of this series, so you get a basic idea on how to expose your web service so that Salesforce can connect to it. In this part, we will do the fun stuff – building an Apex class that can call this web service. Before we proceed, let us revise what happens when Salesforce calls our web service -

1 – Our custom Apex class hosted on the Salesforce.com platform makes an outbound web service call.
2 – The call reaches our modem that forwards it to the wireless router.
3 – Since port forwarding is turned on, the router then forwards the request to our computer’s IP Address.
4 - The computer’s firewall intercepts the request, and since we opened port 80 on the firewall, lets it pass through.
5 – The IIS on the computer receives the web service request, and services it.

Now that we have the basics cleared off, let’s get into the specifics – here are step-by-step instructions on building an Apex class that calls your web service :-

• First, we need to get the WSDL file for our web service. The WSDL(Web service definition language) file is an XML-based representation of our web service – what methods it contains, data types of method parameters, return types, and the communication protocol related details.
• To get the WSDL, simply open a browser and navigate to your web service, passing in ?wsdl as a query string parameter. For my web service, I navigated to http://localhost/MyWebService/Service1.asmx?wsdl (if you haven’t yet hosted the web service on your computer, read Part I of this article series.
• If your web service is hosted correctly, you should see a block of XML in your browser window. Save this as a file with .wsdl extension.
• Next, log into Salesforce.com, and go to Setup->Develop->Apex Classes. A list of classes shows up. Here, click on the “Generate from WSDL” button.

• On the next screen, click the “Choose File” button, and select the WSDL file you had saved previously. Click the “Parse WSDL” button to check the validity of the WSDL file.
• Did you get an error saying “Error: Failed to parse wsdl: Found more than one wsdl:binding. WSDL with multiple binding not supported” ? Well, that happens because the WSDL file generated for an Asp.Net web service has multiple bindings.
• Let me get into a little more detail – if you open and inspect the WSDL file, you will see a <wsdl:binding> element. The binding element defines how to use the web service with a particular protocol (e.g. http), the XML encoding, the name of the operation, input/output parameters etc. For some reason, an asp.net web service WSDL file has multiple nodes for bindings. I don’t know why it does that – both nodes appear the same to me, so I don’t see the point of repeating the same information twice. Anyway, this confuses Salesforce.com when we try to import the WSDL to create an Apex class.

• So, we do what any good software engineer would do – remove the extra binding and proceed :). So go ahead, delete the second <wsdl:binding> node. Also remove the corresponding <wsdl:port> node that was using this binding. Try parsing the file again in Salesforce.com – this should go through without errors. When it asked for Apex class name, I used “MyWebServiceApex”.
• Navigate to the Apex class (MyWebServiceApex), and check out the code. Specially note my notes about using the correct IP Address – I cannot stress this enough. By default, Salesforce.com uses http://localhost as the address for the web service – you need to edit that in the class to make sure it is connecting to your web service.

 

Adding a Remote Endpoint

• Before we run the code to call our web service, we also need to let Salesforce know that this web service could be trusted. For this, we define a “Remote Site” – go to Setup->Administration setup->Security Controls->Remote Site Settings.
• Enter your web service address etc. here, and give it a unique name.

• Now you can start testing your web service.

Testing our class via Anonymous blocks

• Next, we will test the class we just created – launch the developer console (Setup->Developer console). Locate the “Execute” text block at the top – this is where we can put our anonymous code block.

• Copy-Paste the below code into the anonymous code block -

Code Snippet

1. MyWebServiceApex.Service1Soap s1 = new MyWebServiceApex.Service1Soap();
2. String result;
3. result = s1.HelloWorld();
4. System.Debug(result);

• When you execute the code, make sure to check the “Open Log” checkbox. This will launch your execution log file as soon as your anonymous block is executed. The piece of code here basically reaches out to the web service hosted on your computer, and invokes the “HelloWorld()” web method.

• Verify the log file, and you should see the output of your “System.Debug” statement in the logs :-

So, these were the steps you can follow to invoke your web service from Salesforce.com. This approach has various applications – you could build an “event” mechanism so that external systems are alerted whenever something happens in Salesforce.com. Or, you could build an external logging facility that logs each and every page visit to an external database. We will explore some of the additional complexities of this process in the next post.