Salesforce API Integration Using SOAP-based Web Services

There are several tomes & tools to help you integrate with the platform; this article will concentrate on WSDL defined web services. Some help texts are specific to certain languages, others favour certain approaches but I’ve found there’s no short-and-sweet guide. As someone who’s nearly drowned in the documentation (including forums, tweets and blogs) I thought I’d try to save – at least some of you – the white-squall that is ‘Learning the basics of SFDC WSDL-based integration’.

I’ll be the first to admit that summarising such a broad topic can be difficult, so if I do miss anything out, y’all out there in the community just let me know.

Web Services Definition Language

So what is this WSDL-thing, and what’s all the furor about? Essentially a WSDL is an XML file that defines a remote application’s methods and data that have been exposed via a URI. How does it do this? Well most of the file uses a predetermined-standard to define the data (Classes) and action-signatures(Methods). We as developers can then use a web services engine (Axis is one example) to generate libraries in the language of our choice, and these libraries – together with the engine – handle the two-way communications viz. outbound call data is serialised into XML for transmission, and inbound XML is deserialised into data structures our programming language understands. Quite a bit to get your head around, and that’s just the beginning.

Authentication

Almost all integrations begin with authentication, and as far as I know there are 3 libraries that can assist namely, the Partner libraries (built from the Partner WSDL), the Enterprise libraries (built from the Enterprise WSDL) and OAuth. The OAuth-method doesn’t rely on WSDLs but it is a really neat way to JUST authenticate; there’re some very cool blog & forum posts about the protocol and it’s implementation on the platform, here are some of my favourites,

• RumbleWare was first out of the starting blocks (Salesforce as an OAuth Provider)
• A rather useful forum post by vbadhwar (Again Salesforce as an OAuth Provider)
• Awesome Apex OAuth library built by jesperfj. I bow to you kind sir. (Salesforce as an OAuth consumer)
• The ‘Help’ link at the top of your logged-in instance also has many a document.

Authentication with the libraries generated from the aforementioned WSDLs is simple and well-documented by Salesforce.

Integration – Partner & Enterprise WSDLs

OAuth rocks, but it’s just an authentication mechanism, therefore we’d typically use either the Partner or Enterprise WSDLs for our integrations as they each facilitate a much richer set of operations. There is a ton of documentation around these WSDLs but this one summarise their purposes succinctly. Over time I’ve realised that the documentation is excellent for developers with a background in web services, but for those without such experience it’s all Greek. So for those of you out there who are struggling to grasp the concepts let me point out,

• The Partner WSDL is analogous to dynamic Apex. It doesn’t know directly about objects such as Account or MyCustomObject__c, instead it understands the concept of a generic SObject, and these SObjects can be recognised as Account or MyCustomObject__c by examining the SObjects describe information. Conceptually this is a bit more difficult to grasp for the developer, but the main advantage is that if you modify the Account or MyCustomObject__c metadata you will not need to regenerate the WSDL and the consequent libraries.
• The Enterprise WSDL on the other hand is more static (or strongly-typed). After generating your language-libraries from this WSDL you’ll notice that you’ll have Classes (or other structures) that directly define your objects. After generating your libraries in Java for example, you could do this,

[code language=”java”]

Account a = new Account(); // not possible with the Partner WSDL as it doesn’t define an ‘Account’ type.

[/code]

The major disadvantage here is that if you added a new field to the Account object, or altered it’s metadata in some other way you’d need to regenerate the WSDL and consequent libraries. Note: The documentation regarding which metadata changes affect the WSDL structure can be found here.

Some examples of when you might use the Enterprise WSDL are: your metadata never changes (unlikely over the long-run), or you have full control over the Salesforce instance and the integrating application. I would highly recommend using the Partner WSDL when Third-Party developers need to integrate with your instance as this gives you the freedom to modify your metadata till kingdom-come, and they won’t (for the most part) notice.

Integration – Apex Web Service Methods

There is another way to interact with methods defined on the platform, and it’s this area of the documentation that needs the most TLC (out of the current topics that is). There are some articles on how to define web services methods in Apex,

• The basics
• A bit more meat on the bone

The second article is excellent but there are some other key areas I’d like to address..

When should I use this method of interaction?

The two main use-cases for this type of WSDL integration are,

• An integration is currently using either the Partner or Enterprise WSDL but for whatever reason you need to expose a custom method in addition to what those APIs already facilitate.
• You only need to expose a specific set of functionality via web services and don’t need the full use of the Partner or Enterprise WSDLs.

What should I be mindful of?

There is no better teacher than experience, but some things you should be aware of,

• Governor Limits. Strangely the application of Governor Limits (WRT future calls) is different between development environments and unit tests. Grrrrr..
• Testing these methods can be a headache, so here’s an aspirin.
• Authentication can be awkward. You’ll need to pass your Apex defined web service a session Id to prove that your not a haX0r, and to get this token you’re going to need to authenticate as a Salesforce user. The session Id is returned as part of the login result obtained from any of the authentication methods mentioned in the beginning of the article. This means that you’ll either need at least two WSDLs; or an OAuth library and another library for you web service(s).

In Summary

There are number of ways to integrate external applications with the platform, and an ample amount of documentation to help you on your way; all you need to do is choose the type of integration that tickles your fancy and dive head first into corresponding documentation. Buying a rabbit’s foot for good luck wouldn’t hurt either.