Introduction
The SOAP protocol is one of the many possibilities offered by Salesforce to interact with its database using standard or custom APIs. Using it in a client application can prove difficult if one has no deep knowledge about how the protocol works and how to build the requests. That’s why Salesforce provides us with a file including all the information we need to communicate with an org using SOAP : that’s where the WSDL comes in.
The WSDL (Web Service Description Language) is a language used to contain the information necessary to interact with a given Web Service (WS). It is a XML-based standard that is widely used to create WS clients in different programming languages. In Salesforce, it is useful to create a client that will be able to make calls to the standard SOAP API.
What are the WSDL files ?
As explained before, the WSDLs are files that are useful to create a client of the Salesforce SOAP API. It is generated by an org and consumed by a client to generate a code that serves as a proxy between the client app and Salesforce. There are different types of WSDL that Salesforce offers : the Partner and Enterprise WSDL are used to retrieve and edit Salesforce data like Account via the SOAP API. While the Metadata and Tooling WSDL are used to call respectively the Metadata and Tooling APIs useful to deploy metadata or develop Salesforce IDE apps.
In this article :
- We are going to focus on the Partner and Enterprise WSDLs, as the topic is not about metadata deployment but data modifications. As put in the documentation, the Partner WSDL is loosely typed and static. While the Enterprise WSDL is strongly typed and tied to a specific Salesforce configuration.
- We will see later what that means by seeing how each of these files are used in the context of a client app with some concrete examples.
The WSDL files are accessible in any Salesforce org, in the setup under Integration -> API. Here can be found different links corresponding to the different WSDL files available, including the Partner and Enterprise.
It is to be noted that WSDL can also be used in the other way to create Apex class as client of external Web Services. This is done in the setup under Custom code -> Apex classes by clicking the “Generate from WSDL” button, as explained here and using the WSDL provided by the external service.
This will create a proxy code in Apex that can be used to make external calls to the WS.
Client project setup
Before going in the details of the WSDL and how to use them, let’s first set up the client project that will make the API calls.
Here we’ll create a Java project using the Eclipse IDE, but any other IDE and language works as well.
We need two files :
The WSDL (Partner or Enterprise, in the next examples we use the Partner) that can be generated in the org as explained above, and the WSC (Web Service Connector). It can be found here as explained in the Salesforce documentation or in the Git repository.
This file is important when converting the WSDL into Java classes. It contains valuable code as well to connect to your org (among other things as well).
Then, we compile the stub code using both WSDL and WSC files with the command provided in the documentation (this example uses the Partner WSDL but the same procedure applies with the Enterprise one) :
java -classpath pathToJar\force-wsc-XX.X.X-uber.jar com.sforce.ws.tools.wsdlc pathToWSDL\wsdlFilename .\wsdlGenFiles.jarThis generates a file (in our example wsdlGenFiles.jar) that is a library containing the proxy code that allows the interaction with Salesforce. All we need to do then is to reference both the WSDL and WSC libraries in the project (for instance, a Build path in Eclipse) and import them before any class with :
import com.sforce.ws.*;
import com.sforce.soap.partner.*;
import com.sforce.soap.partner.sobject.*;After we have generated and linked the Salesforce libraries to our project, we can analyze further the purpose of each one.
There is the force-wsc-49.3.0-uber.jar library that contains, among other things, the classes necessary to initiate a connection to an org.
The other library is partner.jar that contains the classes to interact with the SOAP API.
So the main package (com.sforce.soap.partner) contains the classes and methods to send instructions to an org.
And the com.sforce.soap.partner.fault package contains various classes including the ones necessary for error handling.
Finally the last package (com.sforce.soap.partner.sobject) is where the main difference between Partner and Enterprise WSDL lies, and it will be detailed in a later section.
Now, before making any attempt to call the SOAP API …
We need to create a connection to the org, which needs a proper authentication. This is done using the following bit of code :
ConnectorConfig config = new ConnectorConfig();
config.setUsername(username);
config.setPassword(password);
config.setAuthEndpoint(authEndPoint);PartnerConnection connection = Connector.newConnection(config);where username, password and authEndPoint are String variables defined in the code. The username and password are the user credentials (for the password, we need to append the security token after the user password as well). The authEndPoint string is a url on the form: https://[org name].my.salesforce.com/services/Soap/u/[version number]/. We thereafter use this connection object to initiate any call we make to Salesforce.
Here we are, we’ve generated the proxy code necessary to our project, now let’s see in a bit more details what these WSDL are.
The Partner WSDL
Let’s start with the Partner WSDL :
If we recall the documentation, this file is loosely typed and static. The static part means the file does not change when there is a change in the org customization, hence it can be used to interact with any configuration of org. This means that an application using the Partner WSDL will not need to generate its proxy code every time there is a change in the org, it thus requires less maintenance. About the “loosely typed” part of the description, we’ll see in details what it means in this section.
Let’s look a bit closely to the structure of the file itself :
As an XML file, it is composed of a hierarchy of tags nested one into the other. Each of these tags will be interpreted by the compiler and translated into something in the proxy code, either a class or a method, for instance.
Here is what we get when we look more closely at the first part in our Partner WSDL :
<schema elementFormDefault=”qualified” xmlns=”http://www.w3.org/2001/XMLSchema" targetNamespace=”urn:sobject.partner.soap.sforce.com”>
<import namespace=”urn:partner.soap.sforce.com”/>
<! — Dynamic sObject ->
<complexType name=”sObject”>
<sequence>
<element name=”type” type=”xsd:string”/>
<element name=”fieldsToNull” type=”xsd:string” nillable=”true” minOccurs=”0" maxOccurs=”unbounded”/>
<element name=”Id” type=”tns:ID” nillable=”true” />
<any namespace=”##targetNamespace” minOccurs=”0" maxOccurs=”unbounded” processContents=”lax”/>
</sequence>
</complexType>
</schema>The first section is a schema tag, that will be interpreted as a Java package when the WSDL is consumed. This contains an import tag, followed by a complexType that represents a class.
This tag includes a sequence section that contains a list of element tags, each representing a method or an attribute of this object.
So from what we observe in the file we expect that the proxy code created using this file is going to include a class named SObject that contains several attributes such as Type or Id and the associated setter and getter methods.
Indeed this is what we find in the com.sforce.soap.partner.sobject package. We also see that the class extends another class, XmlObject, that is defined in the WSC file that we used above to compile the libraries. This SObject class can represent any Salesforce object (such as Account or Case, for instance). That is the class we are going to use when calling the API.
This is what is meant by “loosely typed” in the WSDL definition : there is not a specific class for each SObject but rather a generic class that will have to be attributed a type.
Here is a sample code to create an Account as an example(similar to the documentation example) :
SObject account = new SObject();
account.setType("Account");
account.setField("Name", "Test");
SObject[] accounts = new SObject[1];
accounts[0] = account;
SaveResult[] results = connection.create(accounts);As we can see, the first step after creating the SObject is to set its type, then we can set any field using the syntax : variable.setField(“fieldName”, “value”);.
We then put this variable into a list and use the create() method of the connection object we created earlier to insert this list.
There is also the possibility to use update() or upsert() methods, and there is a wide variety of methods that are available such as convertLead() or findDuplicates().
The response of the request is stored in the result variable that we can use to check the success of the record creation and more details like the record Id (in case of a success) or an error message (in case of failure).
Hence, because of its loosely typed property, the Partner WSDL is used for application that retrieve information about an object (with methods like describeSObject(), for instance) before interacting with this object. In that case, the type of the object being handled is one of several parameters.
The Enterprise WSDL
Now we have seen what are the distinctive features of the Partner WSDL. We can guess what the Enterprise WSDL definition means : strongly typed and tied to a specific Salesforce configuration.
Strongly typed, as opposed to loosely typed, means that the SObject class will be replaced by more specific classes (even though the SObject class still exists). It results from this that it will be bound to a single Salesforce configuration (indeed, if a new object is added to and org, it automatically makes any previous Enterprise WSDL obsolete).
This also implies that the Enterprise WSDL is generally a much bigger file than the Partner (24000 lines against 7900 in our example), as it must contain the information about the metadata present in the org.
The structure of the file is similar to the Partner WSDL, except it contains not only a definition of the SObject but a large number of other objects such as the Account, as shown below (abridged version) :
<complexType name="Account">
<complexContent>
<extension base="ens:sObject">
<sequence>
<element name="AccountCleanInfos" nillable="true" minOccurs="0" type="tns:QueryResult"/>
<element name="AccountContactRoles" nillable="true" minOccurs="0" type="tns:QueryResult"/>
<element name="AccountNumber" nillable="true" minOccurs="0" type="xsd:string"/>
<element name="AccountPartnersFrom" nillable="true" minOccurs="0" type="tns:QueryResult"/> ...
<element name="Type" nillable="true" minOccurs="0" type="xsd:string"/>
<element name="UserRecordAccess" nillable="true" minOccurs="0" type="ens:UserRecordAccess"/>
<element name="Users" nillable="true" minOccurs="0" type="tns:QueryResult"/>
<element name="Website" nillable="true" minOccurs="0" type="xsd:string"/>
<element name="YearStarted" nillable="true" minOccurs="0" type="xsd:string"/>
</sequence>
</extension>
</complexContent>
</complexType>In this case, we have classes that represent each object in your org including the custom objects. This means that the type of each object we would use is more strongly defined in the proxy code, which is what is meant by “strongly typed”.
The enterprise WSDL thus allows you to manipulate directly your objects, with the associated fields. On the other hands you need to re-generate the WSDL and consume it again every time you make a change in an object which is not the case with the partner WSDL.
Here is a sample code to create an Account as in the previous example, this time using the Enterprise WSDL :
Account a = new Account();
a.setName("AccountTest");
Account[] accounts = new Account[1];
accounts[0] = a;
SaveResult[] results = connection.create(accounts);Unlike with the Partner WSDL, this time we don’t have to set the object type as it is a different class we manipulate. There are specific methods associated to each field (that contain the API name of the field) to either get or set it.
The same methods as with the Partner WSDL (update(), convertLead(), etc…) are available as well.
It is to be noted that, as another difference with the Partner WSDL, the connection uses an EnterpriseConnection instead of the PartnerConnection to connect with the org.
Also the endpoint url is of the form https://[org name].my.salesforce.com/services/Soap/c/[version number]/ (note the c instead of the u).
The fact that a lot of elements of configuration are present in the Enterprise WSDL means that one would need to generate and compile it again to take into account any new piece of customization in the client app. But this also makes the client code more readable as well. So it can be suited for some applications where there is a unique link between an org and a client app.
Summary
In summary, the Partner WSDL is more likely to be used in applications that would dynamically inspect object properties before using it.
For instance when an application works across several orgs. Because it is loosely typed, it requires to set the type of each object in use, but it does not need to be re-generated every time there is a modification in the org (only once for each release). This makes it a strong candidate to be used in flexible applications that could make calls to several Salesforce organizations.
On the other hand, the Enterprise WSDL is strongly typed which means it is bound to a specific org. Any modification in the customization needs a new consumption to be taken into account. This doesn’t require to inspect the metadata before using it but prevents from working across multiple orgs. The fact that each object has a designated class also makes the code more readable.
In conclusion, there is a tradeoff between maintainability, readability and flexibility that should be considered when choosing between Partner and Enterprise WSDL. That also depends on the specific context of each usage of the SOAP API.
In any case, the possibilities offered by the SOAP API are the same regardless of the type of WSDL that is used. Furthermore, we saw that it allows a great variety of operations to be performed on the Salesforce data.
