Introduction
This blog post is second in the Learning Salesforce Integration series, a continuation of An Introduction: Integrating with the Salesforce Force.com Platform. Talking more about SOAP API, we understand that it is one way that allows us to build inbound web services (WS) using minimum customization within Salesforce. That means the client application needs to import the WSDL generated from Salesforce into their system, create the relevant request message, and invoke the WS; having said that, the most critical of these steps, formation of the request message, needs to be properly understood. As it will differ for different API calls, like create(), update() etc., and Salesforce does not restructure it before consuming it, it is therefore the responsibility of the client application to send the correctly structured message.
So let us derive our main focus for this article:
- Understanding the SOAP API WSDL message structure
- Building the Request Messages for different API call scenarios
- Working Examples
SOAP API Web Service Definition Language
Salesforce provides two out-of-the-box WSDLs for integrating with client applications using inbound web services. These are Enterprise WSDL and Partner WSDL.
Enterprise WSDLs are used by client applications that usually integrate with a single Salesforce Organization, i.e., they build integration around the same Business Object structure. Therefore, Enterprise WSDL comes with defined objects and fields structure with specific data types. Whenever there is any change in the Salesforce side with respect to the Objects or Fields, the client application needs to re-consume the modified WSDL.
Partner WSDLs can be used for integrating with various Salesforce Organizations, each having a different Business Object structure. It does not define the objects and the fields; therefore, the client application needs to consume it only once per version.
As in any other inbound web service integration, the client application needs to build the Header and Body sections of the request message and then invoke the Salesforce end point. A slight difference here is in the approach of establishing the connection with Salesforce in the case of implementing security. In the previous blog post, An Introduction: Integrating with the Salesforce Force.com Platform, we looked at the two steps to integrate with Salesforce – first, retrieving the SessionID and the ServerURL by calling the login() API and second, invoking the end point (i.e. the ServerURL) with the structured request message.
There are several operations or APIs that are available for our use. And these are clubbed together in categories like:
- Core Calls – mainly works on the Salesforce data like query, delete, insert
- Describe Calls – retrieval of various metadata like Object field list and properties
- Utility Calls – utility tasks like setting/resetting password, retrieving user info
A complete list of API calls is available in the Salesforce Documentation.
Building the Request Message
In this section we first take a quick look at an API message and later we have some working request messages for certain requirements where these API calls can be used.
If the client application consumes the WSDL and looks at the generated blank message, it looks like this:
(Use SoapUI in case there is no client application available for consuming and testing the WSDLs and the API calls.)
The API provides various Headers to the client applications. The most important and necessary to use is the SessionHeader. In this header, within sessionId, the client application needs to send the session ID retrieved from the Salesforce instance using the login() API call. The API won’t work if there is no session ID provided.
Let’s take a look at few of the other headers.
AllOrNoneHeader gives the control to commit or roll back changes to the records sent when there are any failed records. The default is false, which means the successful records are committed and the failed records are returned with the error message. If it is made true, then the presence of any failed record results in complete roll back. A simple application of it could be a scenario where we require not committing the parent record if there are any failed child records.
AssignmentRuleHeader helps specify the Assignment Rule in case of creating or updating Case, Lead, and Account. Example: Running the specified assignment rule (which can be active or inactive) when a new case is created.
EmailHeader helps trigger emails. As in the case of different user interface events like creating a case, resetting user password, etc., emails are triggered, similarly using this header in the sent message, emails can be made to trigger. A simple usage is triggering an email to the contact associated with a case that is newly created through the API.
There are other headers as well that can be used. For more details about the ones mentioned above and others, refer to the SOAP API Developer’s Guide.
In the next section, we will look at some of the working examples featuring the various SOAP API calls. This will provide you with a starting point towards using the inbound integration for various implementation requirements.
Working Examples
Login() API Call
Scenario 1: Retrieving the session ID and server URL for a session using the login() API.
| XML Message
Response |
Create() API Calls
Scenario 2: Creating a single salesforce record using the create() API.
Description: A single record for any Salesforce object – Standard or Custom, can be created using this API call. In this example, the Account record will be created.
| XML Message |
Response
Scenario 3: Creating multiple unrelated Salesforce records using the create() API.
Description: Multiple records for different objects that are unrelated can be created using this API call. In this example, the Contact and Service Request (Custom Object) records will be created.
| XML Message |
Response
Scenario 4: Creating related records having a parent-child relationship using the create() API.
Description: Multiple records for different objects having a parent-child relationship can be created using this API. In this example, the Account and Contact records will be created having the parent-child relationship.
| XML Message |
Response
Scenario 5: Creating related records having a self-relationship using the create() API.
Description: A self-relation can be created using this API, but not in a single call. First the parent record needs to be created, followed with another API call to create the child record containing the foreign key field referencing the parent record. In this example, the Account and its Parent Account will be created having a self-relationship in two consequent calls.
| XML Message |
NOTE – The ParentId tag needs to contain the ID of an existing Account record that is parent to this new Account.
Response
Scenario 6: Creating related records having an M:M relationship using the create() API.
Description: Multiple records for two objects having an M:M relationship using the junction object can be created using this API. In this example, the records for two custom objects, Merchandise and Invoice, will be created having an M:M relation using the junction object Line Item.
| XML Message |
Response
Update() API Calls
Scenario 7: Updating unrelated records using the update() API.
Description: Multiple records for different object types can be updated in a single call using this API. The ID needs to be provided for each record to be updated. In this example, the records for Account and a custom object, Merchandise, will be updated.
| XML Message |
Response
Scenario 8: Updating the ownership of a record using the update() API.
Description: The ownership of a Salesforce record can be changed using this API. The Salesforce owner ID of the to-be owner needs to be provided by the client application. In this example, the owner of the custom object, Merchandise, is changed.
| XML Message |
Response
Scenario 9: Updating the parent of a record using the update() API.
Description: The parent of a record can be modified using this API. This scenario can utilize even the foreign key to change the parent, if not the s=Salesforce ID of the parent record. In this example, the parent Account record of Merchandise will be updated.
| XML Message |
Response
Upsert() API Call
Scenario 10: Creating/Updating records using the upsert() API.
Description: This is the most recommended API to use instead of create() to avoid duplicity. It updates/creates records depending on whether they exist or not. Records of only one object type can be sent in a single call. For example, per the message below, one of the account records is updated, while the other is created based on the foreign key.
| XML Message |
Response
Delete() API Call
Scenario 11: Deleting records using the delete() API.
Description: Multiple unrelated records can be deleted simultaneously using this API. Only the Salesforce record ID for the records to be deleted needs to be provided. In this example, records of Account and Merchandise objects are deleted.
| XML Message |
Response
Query() API Call
Scenario 12: Querying records using the query() API.
Description: Records from a specified object can be retrieved using the query() API call. In this example, Account is queried and the records matching the criteria are returned as the response.
| XML Message |
Response
There are other useful Core calls like undelete, emptyRecycleBin, etc., which are straight forward to use and provide further ways to manage Salesforce data from outside Salesforce.
Other types of calls like describeSObject, describeTabs, etc., provide insight into the Salesforce configuration (or the metadata). These details are useful while executing the regular core calls. For example, the relationship name between a standard and custom object can be retrieved from a describeSObject call for the custom object to be used in a create() call.
Summary
The SOAP API provides various predefined ways to work on the Salesforce data from a client application, outside of Salesforce. Some of the scenarios shown in this article should help give a quick start. Though it limits the solution by not providing necessary flexibility to handle complex business processes, it proves advantageous for the ease it brings to integrate with Salesforce.
The next level, therefore, is to handle complicated requirements which cannot be dealt with in these direct, predefined calls. This is where APEX Web Services or Call-outs should be useful.
Last in the series, APEX: Opening Ways To Integrate Salesforce, details this next level. It discusses the usage of Apex in building seamless integration around complex business requirements. Take the benefit of the sample codes illustrated to quickly create working integration.
References
About the Author
Anupam Rastogi is a CRM Consultant working in CSC, with rich experiences in popular CRM products like Salesforce and Oracle Siebel CRM. His expertise includes niche areas like integrations, coding, etc. Having worked in several domains like Public Sector, Sales, Marketing, Call Center, Order Management, Aviation, Energy and Telecom, he has a great sense of designing CRM applications around business needs. He aims at becoming one of the finest Consultants in the CRM world, sharing his experiences with businesses worldwide. His leisure time activities include photography (and playing with its associated software, like Lightroom, Photoshop), cooking, and traveling.
He can be reached @ anupam.rastogi@gmail.com or LinkedIn Profile.